implement

name	implement
description	Full TDD loop — plan, branch, write code + tests, format, lint, test, review, commit.

/implement

Drives feature implementation from story acceptance criteria using TDD.

Prerequisites

• A story file at stories/S-NNN-*.md with the status: in-progress and branch: set.
• Currently on the story's branch (feature/S-NNN-<slug>).

Steps

1. Load the story.

cat stories/S-NNN-*.md

Acceptance criteria are the spec. Each must be addressed.

2. Plan. Read the relevant parts of ARCHITECTURE.md and existing module code to produce an implementation plan. List:

• Files to add or modify (Swift source, tests, project.yml updates)
• New types / protocols / extensions
• Risks (e.g. force-unwraps, sendability, actor isolation)

Wait for user approval before writing code.

2a. Persist plan to story. Append the approved plan to the story file. This captures the implementation approach for future reference.

story_file=$(ls stories/S-*.md 2>/dev/null | head -1)
if [[ -n "$story_file" ]]; then
  cat >> "$story_file" << 'PLANEOF'

## Implementation plan

<the approved plan text — files, types, protocols, risks>
PLANEOF
fi

Then git add the story file so the plan is version-controlled alongside the code.

3. Branch check.

git rev-parse --abbrev-ref HEAD

Must be feature/S-NNN-<slug>. If on main, halt: run the story skill to set status=in-progress first.

4. Write code + tests together (TDD). For each unit of behaviour:

• Add a test first (mark with XCTExpectFailure if desired).
• Implement until the test passes.
• Run only the relevant test suite to get fast feedback:

  swift test --filter <TestTarget>
  

Key Swift conventions:

• Use struct over class unless reference semantics are required
• Use enum for typed errors (Error conformance)
• No force-unwraps (!) in production code (except // SAFETY: justified)
• Use actor for shared mutable state
• Prefer Result<Success, Failure> over completion handlers
• Add new dependencies in Package.swift, then run xcodegen generate

5. Format.

swift format --recursive Sources Tests --in-place

6. Run tests + lint.

swift test 2>&1
swift format lint --recursive Sources Tests 2>&1

• If tests fail: fix and re-run. List each failing test with a one-line reason.
• If lint violations: fix them. Max 3 fix loops, then surface.

7. Code review. Run the review skill (.nidex/skills/review/SKILL.md). Auto-apply mechanical fixes. Surface [needs-decision] items. Re-run tests after changes.

8. Commit. Run the commit skill (.nidex/skills/commit/SKILL.md).

Don't

• Combine unrelated changes. Two features = two runs = two branches.
• Skip the plan step "because the change is small".
• Use // swiftlint:disable without justification.
• Loop indefinitely on failing tests — after 3 iterations, escalate.