> workflow / ai-coding
AI Coding
Implement only approved plan slices inside hooks, stack skills, and architecture boundaries — with tests and docs landing in the same change.
What should I do next?
Complete the steps and evidence below, clear the human gates, then continue to Code Review.
When to use
- Plan approval HITL has passed for the slice
- Context package and stack skill are available to the agent
- pre-code.hook.sh is green for the target slice
- You are executing, not exploring new architecture
Step-by-step
- Load the approved plan slice, ADR IDs, and context package — refuse out-of-plan work.
- Select the stack skill (react/node/python/…) and coding.prompt for generation.
- Implement the smallest vertical change that satisfies the slice DoD.
- Add or update tests with the slice; do not defer "tests later".
- Run debug.skill on failures; do not randomly regenerate large diffs.
- Update docs/runbooks touched by the change; run post-code hooks.
- Open a PR scoped to one slice; link plan item and ADR IDs.
Decisions to make
- Stop and replan vs push through when reality contradicts the plan
- Refactor in-slice vs separate debt ticket
- When to pair-program instead of solo agent execution
- Whether a spike invalidated assumptions enough to return to human-review
Evidence to collect
- Feature branch with slice-scoped commits
- Tests and hook results attached to the PR
- Plan item ID referenced in PR description
- No new integrations beyond ADR allowlist
Role-specific next actions
- PM: Watch for scope creep in PRs; bounce work that is not on the approved plan.
- Architect: Spot-check boundary violations in early PRs of a new area.
- Engineer: Drive the agent; own correctness, tests, and hook compliance.
- QA: Validate test deltas cover the slice acceptance criteria.
Inputs
- Approved plan slice
- Context package and stack skill
- Hook baseline (pre-code / post-code)
Outputs
- Feature branch / PR
- Tests and updated docs
- Hook evidence for the change
Required prompts
- Coding
Primary generation prompt constrained by plan and context.
- Refactoring
Use only for in-slice refactors with tests — not drive-by rewrites.
Required skills
- Debug
Hypothesis-driven failure isolation when generation breaks.
- Testing
Keep proof co-located with the change.
- Documentation
Update operator-facing docs in the same PR when behavior changes.
Required MCP servers
- GitHub MCP
Open/update PRs and read review threads without leaving the harness.
- Filesystem MCP
Scoped file ops when the agent runner requires MCP file access.
Tooling & handbook
- Hooks in practice
Operational guide for pre/post-code gates.
- post-code hook
Post-generation checks before PR.
- pre-commit hook
Local secret/lint gates.
- Code quality standard
Bar for AI-authored code.
- Coder agent
Default coding agent definition.
Recommended agents & patterns
- Debug pattern
When generation fails — isolate before regenerating.
- Coder agent
Primary execution agent under plan constraints.
- Frontend / Backend agents
Use stack-specific agents when the slice is UI or API heavy.
Human approval gates
- No merge without passing hooks
- Out-of-plan changes require returning to implementation-planning / human-review
Automation opportunities
- post-code and pre-commit hooks in local + CI
- Stack cookbook generate prompts for idiomatic code
- Budget guards on token spend for long agent sessions
Enterprise best practices
- Budget-guard.hook.sh for token spend on large slices
- No secrets in prompts, logs, or agent memory
- Attribute AI-assisted commits for audit where policy requires
Common mistakes
- Coding without an approved plan file
- Disabling hooks to "move faster"
- Accepting huge unrelated refactors from the agent in a feature PR