Coding Workflow#

A Research → Plan → User Review → Implement 4-stage procedure for code change tasks.

Configuration#

OptionDefaultDescriptionoutput-dirConfigured WSCFG_ARTIFACTS_PATH (default: .agents/docs/generated)Directory for generated research, plan, and walkthrough files; authoritative domain knowledge may be promoted to LLM Wiki via raw-ingest

Set via project CLAUDE.md, workspace profile config, or skill invocation argument:

text

/code-workflow --output-dir .agents/docs/generated

Task Checklist Registration (MANDATORY Tool Call #1 HARD STOP)#

Upon invoking /code-workflow, registering/updating the task checklist MUST be Tool Call #1. No research commands ( run_command), file inspection ( view_file), or search ( grep_search) may precede task checklist registration.

Checklist medium is environment-scoped (HARD STOP): task.md is the Antigravity task artifact only. Claude Code sessions register via TaskCreate/ TodoWrite; when those tools are unavailable or disabled in the session, fall back to a session-scratchpad checklist file (a .md under the session's scratchpad directory) — never the workspace .agents/task.md, which belongs to Antigravity sessions and must not carry another harness's session state.

TDD Red-First Task Breakdown (MANDATORY Default HARD STOP)#

TDD is the default implementation discipline. When breaking down tasks in task.md or implementation_plan.md, failing test creation (Red) MUST be registered as an explicit task item BEFORE feature implementation (Green) (e.g. - [ ] 🧪 Write failing test (Red) -> - [ ] 🛠️ Implement feature (Green) -> - [ ] 🔄 Refactor). Writing production code before tests without explicit --no-tdd opt-out is strictly forbidden.

Walkthrough Topic-Based Slug Policy (HARD STOP)#

Write walkthrough.md artifacts to the configured output-dir (resolved via WSCFG_ARTIFACTS_PATH, default .agents/docs/generated) — the same destination the Configuration table above already assigns to research and plan files. Do not hardcode a wiki path: a walkthrough is a tool working note, and promoting one to the LLM Wiki goes through raw-ingest after the knowledge-sharing ask in steps.md, never a direct write.

NEVER use generic date filenames (e.g. walkthrough-2026-07-22.md). Always name the file using a descriptive topic-based slug matching the core feature, issue, or plan (e.g. {output-dir}/walkthrough-agent-lifecycle-abstraction.md).

Trade-off Decision Ask (MANDATORY Plan Post-Write HARD STOP)#

After authoring or updating any plan-*.md file that contains 2+ technical options or a Trade-offs table, you MUST invoke AskUserQuestion specifically presenting the trade-off decision axes and alternatives to the user before proceeding to execution. Combining or skipping technical trade-off decisions is strictly forbidden.

Trivial tasks such as simple configuration changes or 1~2 line edits may skip this workflow.

Topics#

TopicDescriptionGuideimplementStep 4: TDD cycle, test level selection, build & commitimplement.mdprCapture + PR creation with visual attachmentspr.mdstepsSteps 0-3: resume check, research, plan, user review, branchsteps.md

Topic Dependencies#

text

code-workflow (steps 0-4)
  ├─→ steps Step 0: GitHub repo detection → loads github-flow as default companion
  ├─→ steps Step 0: github-flow/dependencies (blockedBy precondition check on linked issue)
  ├─→ tdd/cycle (step 4: TDD implementation)
  ├─→ tdd/run (step 4: test execution after implementation)
  ├─→ github-flow/plan-to-issue (auto-trigger when task has linked issue number)
  ├─→ github-flow/dependencies (auto-trigger when plan frontmatter has `chain:`)
  ├─→ github-flow/pr (optional: create PR with visual attachments)
  │     └─→ web-browser (capture via Playwright)
  └─→ github-flow/merge (after PR ready: gates CI/Review/Test Plan/blockedBy)

• Steps 0-4 are always executed (unless trivial)
• GitHub repo auto-load (Step 0): When git remote get-url origin contains github.com, github-flow becomes the default companion — issue/PR/merge ops route through its topics. Non-GitHub remotes fall back to manual gh/ git
• blockedBy precondition (Step 0): Linked issue's blockedBy is queried. OPEN predecessors → switch task or BLOCKED report
• github-flow/plan-to-issue: converts plans to GitHub issues. Auto-trigger when the task has a linked issue number (e.g., Issue #176). Manual trigger when user explicitly requests issue registration
• github-flow/dependencies: applies chain: frontmatter as native Issue Dependencies. Auto-trigger when plan has chain: array. Skipped for single-issue plans
• github-flow/pr (optional, opt-in only): creates PRs. Invoke ONLY when the user explicitly requests PR creation (e.g., "create PR", "open PR"). Never auto-trigger from Step 4 completion
• github-flow/merge (after PR ready): pre-merge gates include blockedBy open-predecessors check (see dependencies.md and merge.md step 3.5)
• tdd is applied by default in step 4. Opt-out with --no-tdd

Quick Reference#

Steps (Research → Plan → Review → Branch)#

1. Step 0: Resume check — read existing research/plan files before starting
2. Step 1: Research — deep codebase reading, write to research-<N>-<slug>.md
3. Step 2: Plan — detailed plan with 6 mandatory sections (including human review questions)
4. Step 3: User review — report BLOCKED, wait for approval, then create branch/worktree

See steps.md.

Implement (TDD)#

• Select test level (unit/integration/E2E) based on change type
• TDD Red commit (test only) → Green commit (implementation) → Refactor
• Monorepo full build verification before commit
• After completion: report only — do NOT auto-trigger push or PR. push and github-flow/pr require explicit user instruction (e.g., "push", "create PR"). PR creation is publish to GitHub and cannot be silently undone; reporting completion does not authorize it (HARD STOP).

See implement.md.

PR (with Visual Evidence)#

• Capture screenshots/GIF/video after implementation
• Attach to PR body (before/after comparison)
• Opt-out with --no-capture

See pr.md.

Applicability by Task Complexity#

Task ComplexityScopetrivial (12 line edits, config value changes)Can be skipped — implement directlymoderate (310 files, logic changes)Start from step 2 (plan)complex (10+ files, new features, architecture changes)Perform all steps from step 1 (research)

Cases where skipping is prohibited even if the line count is small (HARD STOP):

• Regression issues — when something that previously worked is broken. Executable test code (no manual curl/ssh) must be included in the Plan and the issue.
• Primary Branch Integrity (HARD STOP) — every working branch must be cut from the project's latest primary branch (origin/master, origin/main, or origin/develop). git fetch origin and primary-branch confirmation are required before branch creation.
• External system integration changes (Authentik, OAuth, external APIs) — Plan + integration tests are mandatory regardless of line count.
• Authentication/security-related changes — Mandatory to specify test strategy (unit/integration/E2E level) in the plan.
• proxy.ts/middleware branching changes — Affects multiple cases. Mandatory to specify impact scope + GUARD comment strategy in the plan.