|
| 1 | +# Implement Workflow |
| 2 | + |
| 3 | +A story-to-code workflow that takes a Jira Story, plans the implementation, writes contract-based tests and production code via TDD, validates against the project's CI expectations, and manages review via GitHub PRs. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +| Tool | Required | Purpose | |
| 8 | +|------|----------|---------| |
| 9 | +| Jira access (MCP or CLI) | For `/ingest` | Fetch Story issue details | |
| 10 | +| GitHub CLI (`gh`) | For `/publish`, `/respond` | Create PRs, post review comments | |
| 11 | +| Git | Yes | Branch management, commits | |
| 12 | +| Project build/test tooling | Yes | Discovered during `/ingest` from project's AGENTS.md, Makefile, CI workflows | |
| 13 | +| Docs repo (local clone) | For `/ingest` | Read PRD and design document for upstream context | |
| 14 | + |
| 15 | +## Phases |
| 16 | + |
| 17 | +| Phase | Command | Purpose | Artifact(s) | |
| 18 | +|-------|---------|---------|-------------| |
| 19 | +| Ingest | `/ingest` | Fetch story, load context, explore codebase | `01-context.md` | |
| 20 | +| Plan | `/plan` | Design implementation approach and test strategy | `02-plan.md` | |
| 21 | +| Revise | `/revise` | Incorporate feedback into the plan | Updated `02-plan.md` | |
| 22 | +| Code | `/code` | Write tests and code via TDD | `03-test-report.md`, `04-impl-report.md` | |
| 23 | +| Validate | `/validate` | Run tests, lint, coverage analysis | `05-validation-report.md` | |
| 24 | +| Publish | `/publish` | Push branch, create draft PR | `06-pr-description.md` | |
| 25 | +| Respond | `/respond` | Address reviewer comments | `07-review-responses.md` | |
| 26 | + |
| 27 | +## Typical Flow |
| 28 | + |
| 29 | +```text |
| 30 | +/ingest EDM-1234 |
| 31 | + → fetches story from Jira |
| 32 | + → loads design document and PRD context |
| 33 | + → explores affected codebase areas |
| 34 | + → discovers validation profile (build, test, lint commands) |
| 35 | + → writes .artifacts/implement/EDM-1234/01-context.md |
| 36 | +
|
| 37 | +/plan |
| 38 | + → designs implementation approach |
| 39 | + → defines interfaces and types (the contracts) |
| 40 | + → plans test strategy (unit + integration) |
| 41 | + → breaks work into ordered tasks |
| 42 | + → writes 02-plan.md |
| 43 | +
|
| 44 | +/revise (optional, repeatable) |
| 45 | + → user reviews plan, requests changes |
| 46 | + → plan updated, consistency maintained |
| 47 | +
|
| 48 | +/code |
| 49 | + → creates feature branch |
| 50 | + → for each task: write tests → write code → review → commit |
| 51 | + → updates 02-plan.md with task completion status |
| 52 | + → writes 03-test-report.md, 04-impl-report.md |
| 53 | +
|
| 54 | +/validate |
| 55 | + → runs full validation suite (discovered during /ingest) |
| 56 | + → analyzes coverage for untested behavioral paths |
| 57 | + → adds tests for gaps, fixes lint issues |
| 58 | + → writes 05-validation-report.md |
| 59 | +
|
| 60 | +/publish |
| 61 | + → pushes feature branch |
| 62 | + → creates draft GitHub PR with Jira link |
| 63 | + → writes 06-pr-description.md |
| 64 | +
|
| 65 | +/respond (repeatable) |
| 66 | + → fetches PR review comments |
| 67 | + → proposes responses (user approves before posting) |
| 68 | + → applies code changes if needed |
| 69 | + → writes 07-review-responses.md |
| 70 | +``` |
| 71 | + |
| 72 | +## Artifacts |
| 73 | + |
| 74 | +All artifacts are stored in `.artifacts/implement/{jira-key}/`. |
| 75 | + |
| 76 | +```text |
| 77 | +.artifacts/implement/EDM-1234/ |
| 78 | + 01-context.md (story context, validation profile) |
| 79 | + 02-plan.md (task breakdown, test strategy — updated as tasks complete) |
| 80 | + 03-test-report.md (tests written, contracts covered) |
| 81 | + 04-impl-report.md (changes, commits, deviations) |
| 82 | + 05-validation-report.md (check results, coverage, regressions) |
| 83 | + 06-pr-description.md (PR body) |
| 84 | + 07-review-responses.md (review comment log) |
| 85 | + publish-metadata.json (PR number, branch, URL) |
| 86 | +``` |
| 87 | + |
| 88 | +## Key Design Decisions |
| 89 | + |
| 90 | +### Contract-Based Testing |
| 91 | + |
| 92 | +Tests validate behavioral contracts through public interfaces: |
| 93 | +- Every behavioral path reachable through a public function gets its own test case |
| 94 | +- Tests should remain valid if the implementation were rewritten |
| 95 | +- Unit tests are always required; integration tests are required when the story touches component interactions |
| 96 | +- Coverage tooling is a signal ("is there a behavioral contract I missed?"), not a numeric target. However, new code that cannot reach the project's coverage threshold (discovered during `/ingest`, default 90%) through public API tests signals a design problem — the component likely needs decomposition into smaller units, not tests that reach into internals |
| 97 | + |
| 98 | +### Discovery-Based Validation |
| 99 | + |
| 100 | +The workflow does not hardcode language-specific commands. During `/ingest`, it discovers the project's validation expectations from AGENTS.md, Makefile, and CI workflows, and records them in a validation profile. `/validate` executes whatever was discovered. If the project adds new CI checks, the next `/ingest` picks them up automatically. |
| 101 | + |
| 102 | +### Incremental Commits |
| 103 | + |
| 104 | +Each logical unit of work gets its own commit, following the project's commit format (discovered during `/ingest`). Each commit should be independently meaningful. |
| 105 | + |
| 106 | +### Plan as Living Document |
| 107 | + |
| 108 | +`02-plan.md` is updated during `/code` as tasks are completed. On re-invocation (e.g., after context limits or interruptions), the plan shows which tasks are done and which remain. |
| 109 | + |
| 110 | +## Directory Structure |
| 111 | + |
| 112 | +```text |
| 113 | +implement/ |
| 114 | +├── SKILL.md # Workflow entry point |
| 115 | +├── guidelines.md # Behavioral rules and guardrails |
| 116 | +├── README.md # This file |
| 117 | +├── skills/ |
| 118 | +│ ├── controller.md # Phase dispatcher and transitions |
| 119 | +│ ├── ingest.md # Fetch story, explore codebase |
| 120 | +│ ├── plan.md # Design implementation approach |
| 121 | +│ ├── revise.md # Incorporate plan feedback |
| 122 | +│ ├── code.md # Write tests and code via TDD |
| 123 | +│ ├── validate.md # Run validation suite |
| 124 | +│ ├── publish.md # Create GitHub PR |
| 125 | +│ └── respond.md # Address review comments |
| 126 | +└── commands/ |
| 127 | + ├── ingest.md # /ingest command |
| 128 | + ├── plan.md # /plan command |
| 129 | + ├── revise.md # /revise command |
| 130 | + ├── code.md # /code command |
| 131 | + ├── validate.md # /validate command |
| 132 | + ├── publish.md # /publish command |
| 133 | + └── respond.md # /respond command |
| 134 | +``` |
| 135 | + |
| 136 | +## Getting Started |
| 137 | + |
| 138 | +```bash |
| 139 | +# Install the workflow |
| 140 | +./install.sh claude --workflows implement |
| 141 | + |
| 142 | +# Or install all workflows |
| 143 | +./install.sh all |
| 144 | +``` |
| 145 | + |
| 146 | +Then in your project, run the `implement` workflow's `ingest` command for your Jira story (e.g., EDM-1234). |
0 commit comments