sw-team-implementer

name	sw-team-implementer
description	Methodology for building all five SW-TEAM deliverable types from a design brief: {package}/ Python functions (stateless, typed, tested), spec templates (placeholder-driven .md), SKILL.md files (FIXED/ADAPT scaffolds with Layer A calls), .agent.md definitions (frontmatter + system prompt), and integration artefacts. Loaded by the SW-TEAM-Implementer agent at session startup. Domain-agnostic — contains no project-specific vocabulary. Load alongside a domain-context SKILL (e.g., {domain}-builder-context) for package name, fixture shapes, and commit scopes.
user-invocable	false

SW-TEAM Implementer — Methodology SKILL

Audience: SW-TEAM-Implementer agent only. Domain vocabulary: Zero — all project-specific values come from the domain-context SKILL. Load alongside: <domain>-builder-context/SKILL.md for package name, fixture names, and commit scopes.

---

FIXED — Build Order

When building all deliverables for a phase, follow this order:

1. {package}/ functions first — Code QA can begin validating immediately
2. Spec templates second — SKILL.md scaffolds reference spec fields
3. SKILL.md files third — depend on both {package}/ functions and spec fields
4. .agent.md files fourth — reference SKILL.md paths
5. Integration artefacts last — reference everything above

Signal completion to the SCRUM Master per deliverable, not per phase. This allows QA to run in parallel with remaining implementation.

---

FIXED — Procedure 1: Build a {package}/ Function

Input: one row from design brief Section A.

1. Read the signature from the design brief (symbol, module path, signature, returns, raises, edge cases, test fixture).
2. Open or create the module: confirm the file exists at the expected path. If new file: add from __future__ import annotations and the package __init__ import chain.
3. Enforce mandatory rules (from sw-team-architect SKILL §FIXED — Function design rules):
   • Type hints on all parameters and return values
   • Google-style docstring with Args:, Returns:, Raises:
   • Stateless: no file I/O, no spec reading, no print(), no global mutable state
   • Defensive: raise specific exceptions on invalid input
4. Write the function body strictly matching the design brief specification. If the body requires a design decision not covered in the brief, stop and flag to the SCRUM Master — do not resolve design questions yourself.
5. Write the test in tests/test_{module}.py:
   • Use the fixture name from the design brief (from domain-context SKILL §FIXED — Validation scenario)
   • Follow test naming convention: test_{function}_{scenario}
   • Cover: basic case, edge cases listed in design brief, each exception
6. Sanity check: confirm the module imports cleanly from the package root.
7. Commit: feat({package}): add {function_name}()
8. Signal completion to the SCRUM Master: function path + test path.

---

FIXED — Procedure 2: Build a Spec Template

Input: Section B from the design brief.

1. Read the field list from the design brief.
2. Create the file at templates/<spec_name>_template.md. Never overwrite an existing template without explicit instruction.
3. Enforce structure:
   • Title placeholder: # <Spec Name> — <{identifier_placeholder}>
   • Status: DRAFT field present (to be set to LOCKED when approved)
   • All required fields present with placeholders in <angle-bracket> format
   • No project-specific values in the template body
   • All markdown tables have correct column alignment
4. Cross-check field names against any SKILL.md load_spec_section() calls that already exist. Mismatched field names are a blocking error — flag before committing.
5. Commit: feat(templates): add {spec_name}_template.md
6. Signal completion.

---

FIXED — Procedure 3: Build a SKILL.md

Input: Section C from the design brief.

1. Read the scaffold from the design brief (FIXED sections, ADAPT sections, Layer A calls, validation sandwich).
2. Enforce FIXED/ADAPT contract:
   • At least one ## FIXED section and at least one ## ADAPT section
   • FIXED sections: no project-specific values (no hardcoded column names, no specific numeric parameters)
   • ADAPT sections: instructional comment blocks explaining what the agent fills, from which source, and in what format
   • Validation sandwich: FIXED validation → ADAPT transform → FIXED validation
3. Verify all Layer A references:

   #tool:search/textSearch → "def {function_name}" in {package}/
   

   Every {package}.* function call in the scaffold must resolve to an existing function. If missing: stop and flag — do not write a scaffold with broken Layer A references.
4. Verify output paths use placeholders (e.g., output/{scope_id}/...), not hardcoded paths.
5. Commit: feat(skills): add {skill-name}/SKILL.md
6. Signal completion.

---

FIXED — Procedure 4: Build an .agent.md

Input: Section D from the design brief.

1. Read the prompt architecture from the design brief (frontmatter fields, tool list, handoff prompts, system prompt structure).
2. Enforce frontmatter rules:
   • Required fields: name, description, tools, model
   • Worker agents: user-invocable: false and disable-model-invocation: true
   • Orchestrators: agents: [WorkerA, WorkerB] if they invoke workers
   • User-invocable agents: argument-hint required
3. Enforce handoff self-containment: each handoff prompt must be a zero-history brief. Test mentally: can a subagent with no session history understand what to do from this prompt alone? If not, rewrite until yes.
4. Enforce system prompt structure (in order):
   1. Role statement
   2. Session Startup Sequence (explicit #tool:read_file calls)
   3. Authoritative References table
   4. Responsibilities
   5. Workflows
   6. Non-negotiable Rules
5. Commit: feat(agents): add {agent-name}.agent.md
6. Signal completion.

---

FIXED — Procedure 5: Build Integration Artefacts

For copilot-instructions.md additions:

1. Read the existing file.
2. Add only the content specified in the design brief — do not restructure existing content.
3. Verify: <project_root> definition, artefacts.jsonl protocol, KB protocol, agent invocation rules, output path conventions all present after edit.
4. Commit: feat(infra): update copilot-instructions.md

For KB starters:

1. Create at templates/kb/<prefix>.md if not present.
2. Include: section headers per §KB structure from domain-context SKILL, entry ID format, entry format example (timestamp, agent, phase, description), and structure-only content (no actual entries).
3. Commit: feat(infra): add KB starters

For append_artefact() utility:

1. Implement in {package}/utils/manifest.py (or as specified in design brief).
2. Enforce: JSONL append-only, sequential ID, all required fields, UTC timestamps.
3. Commit: feat({package}): add append_artefact()

---

FIXED — QA Rework Workflow

When the SCRUM Master routes a QA failure back to the Implementer:

1. Read the failure from the QA report. Identify: failing item ID, failure type, file path, and specific deviation.

2. Classify the failure type:

   Failure type	Root cause	Fix approach
   Test failure	Function produces wrong output	Fix the function; re-run test
   Broken Layer A ref	SKILL.md calls non-existent function	Add the missing function or fix the call
   Missing spec field	Spec template incomplete	Add the field with correct placeholder
   Hardcoded FIXED value	FIXED section has project-specific value	Replace with {placeholder}
   Broken import	Module path wrong	Fix import; verify module exists
   Non-self-contained handoff	Handoff prompt has implicit reference	Rewrite prompt as zero-history brief
   Lint error	ruff/mypy violation	Fix at the source; do not suppress

3. Fix specifically — do not refactor unrelated code.

4. Commit: fix: {description of fix} — prefix all rework commits with fix:.

5. Signal back to the SCRUM Master with the original QA failure ID and confirmation.

---

FIXED — Commit Conventions

Follow Conventional Commits with scope:

Prefix	Scope	Use for
feat	{package}	New {package}/ functions
feat	tests	New test files or test cases
feat	templates	New spec templates
feat	skills	New SKILL.md files
feat	agents	New .agent.md files
feat	infra	New integration artefacts (copilot-instructions.md, KB starters)
fix	(same scopes)	Bug fixes and QA rework
docs	docs	Documentation files
refactor	(same scopes)	Code restructuring without behaviour change

Never commit generated artefacts or secrets.

---

ADAPT — Package Name and Paths

Agent instruction: read from domain-context SKILL §FIXED — Package.

• Package name: {package_name}
• Package root: {package_root}/
• Test directory: tests/
• Template directory: templates/
• Skills directory: .github/skills/
• Agents directory: .github/agents/

---

ADAPT — Validation Scenario Fixtures

Agent instruction: read from domain-context SKILL §FIXED — Validation scenario.

• Scenario name: {validation_scenario_name}
• Dataset description: {dataset_description}
• Fixture names in conftest.py: {conftest_fixture_list}
• Expected columns: {expected_column_list}
• Expected shape: {expected_shape}

---

ADAPT — Commit Scope Table

Agent instruction: read from domain-context SKILL §FIXED — Commit scope table.

Use the domain-context SKILL commit scope table to map each deliverable type to the correct Conventional Commits scope for this project.