--- title: "Implement: Rules" description: "6 rules for the Implement skill: Subagents must only modify files within their assigned scope — prevent cross-agent conflicts; Cap changes per agent batch to prevent cascade failures; Commit after each logical milestone — never batch all commits to session end; Block completion if new code has zero test coverage — tests are mandatory for every implementation; Match implementation tier to assessed complexity — never over-engineer a simple task; Always ExitWorktree after implementation — never leave orphaned worktrees" canonical: "https://orchestkit.yonyon.ai/docs/reference/skills/implement/rules" --- # Implement: Rules 6 rules for the Implement skill: Subagents must only modify files within their assigned scope — prevent cross-agent conflicts; Cap changes per agent batch to prevent cascade failures; Commit after each logical milestone — never batch all commits to session end; Block completion if new code has zero test coverage — tests are mandatory for every implementation; Match implementation tier to assessed complexity — never over-engineer a simple task; Always ExitWorktree after implementation — never leave orphaned worktrees > Part of the [Implement](/docs/reference/skills/implement) skill reference. The main page carries the skill itself; this page holds material that used to sit at the bottom of it. ## Rules (6) ### Subagents must only modify files within their assigned scope — prevent cross-agent conflicts — HIGH ## Agent Scope Containment Each subagent spawned in Phase 4-5 must receive an explicit file scope boundary in its prompt. Agents must NOT modify files outside their assigned scope. This prevents parallel agents from overwriting each other's work. ### Problem Claude spawns parallel agents (backend, frontend, test-generator) without defining which files each agent owns. Two agents edit the same file — the last one to finish silently overwrites the first. This is especially dangerous without worktree isolation. ### Scope Assignment Define non-overlapping scopes in Phase 2 (Micro-Planning): ```python scopes = { "backend-system-architect": { "owns": ["src/api/", "src/services/", "src/models/"], "reads": ["src/types/", "src/config/"], "forbidden": ["src/components/", "src/pages/", "tests/"] }, "frontend-ui-developer": { "owns": ["src/components/", "src/pages/", "src/hooks/"], "reads": ["src/types/", "src/api/client.ts"], "forbidden": ["src/api/routes/", "src/services/", "src/models/"] }, "test-generator": { "owns": ["tests/", "__tests__/", "*.test.*", "*.spec.*"], "reads": ["src/"], "forbidden": [] # Can read everything, writes only to test dirs } } ``` **Incorrect — no scope boundaries in agent prompts:** ```python # Phase 5: Agents with overlapping scope Agent(subagent_type="ork:backend-system-architect", prompt="Implement the user auth feature", run_in_background=True) Agent(subagent_type="ork:frontend-ui-developer", prompt="Implement the user auth feature", run_in_background=True) # Both agents edit src/types/user.ts — last write wins, first is lost # Both create src/utils/validation.ts — silent overwrite ``` **Correct — explicit scope in every agent prompt:** ```python # Phase 5: Agents with strict scope boundaries Agent(subagent_type="ork:backend-system-architect", prompt="""Implement backend for user auth. YOUR SCOPE (only modify these): src/api/, src/services/, src/models/ SHARED TYPES (read-only): src/types/ DO NOT TOUCH: src/components/, src/pages/, tests/ If you need a shared type, create it in src/types/auth.types.ts""", run_in_background=True) Agent(subagent_type="ork:frontend-ui-developer", prompt="""Implement frontend for user auth. YOUR SCOPE (only modify these): src/components/, src/pages/, src/hooks/ SHARED TYPES (read-only): src/types/ DO NOT TOUCH: src/api/routes/, src/services/, src/models/ Import API client from src/api/client.ts — do not modify it""", run_in_background=True) ``` ### Shared File Protocol For files both agents need (e.g., shared types): 1. Assign ONE agent as the owner of each shared file 2. Other agents may only read it 3. If both need to add types, use separate files: `auth.types.ts` (backend), `auth-ui.types.ts` (frontend) ### Key Rules - Include explicit scope boundaries in every subagent prompt - Log scope assignments in `02-plan.json` handoff for traceability - After all agents complete, check for conflicting writes to the same file - Prefer worktree isolation (`isolation: "worktree"`) to eliminate conflicts entirely - If an agent violates scope, discard its out-of-scope changes and re-run ### Cap changes per agent batch to prevent cascade failures — HIGH ## When This Rule Applies Large refactors, sweeping renames, signature migrations, or any `ork:implement` run that will modify **more than 10 files**. Also applies when spawning subagents for tasks with broad scope. ## The Rule **Default batch size: 5 files.** Configurable via `--batch-size N` argument to `/ork:implement`. For every batch: 1. **Make the change** (Agent edits up to `N` files). 2. **Run the relevant tests** (`npm test -- <scope>` or framework equivalent). 3. **If green**: commit the batch with a descriptive message, proceed to next batch. 4. **If red**: stop. Do not proceed to the next batch. Debug with the failing batch still uncommitted. Fix the issue before touching more files. 5. **Never skip step 4** with `// TODO`, `# type: ignore`, or `eslint-disable` — those suppress the signal the batch was too large. ## Why From usage analytics across 126 sessions: large one-shot refactors (176-file migrations, 91 exception narrowings) consistently produced cascade failures where one bad change created 50+ test regressions. Sessions that used small batches (≤5 files per cycle) had measurably better outcomes — faster root cause identification, fewer rollbacks, lower turn counts. ## Recognizing the Trigger Before starting an implementation that touches multiple files, run a quick scope estimate: ```bash # Estimate affected files grep -rl "" src/ | wc -l ``` If count > 10, engage batch governance. If > 50, also consider whether the operation needs a pre-written migration script rather than agent-driven edits — at that scale, a scripted `sed` or `codemod` with a single careful review is usually cheaper than 10+ agent batches. ## Incorrect Pattern ```python # Don't: one Agent call to rewrite 176 files Agent(subagent_type="ork:backend-system-architect", prompt="Migrate all repository.py files to the new RepositoryBase pattern") # Result: agent edits all 176, tests fail in 40 places, no clean rollback target ``` ## Correct Pattern ```python # Do: loop with tests between batches files = find_affected_files(pattern) # 176 files for batch in chunks(files, size=5): Agent(subagent_type="ork:backend-system-architect", prompt=f"Migrate these 5 files to the new RepositoryBase pattern: {batch}") result = Bash("npm test -- src/repositories") if result.failed: break # Stop. Debug with current batch uncommitted. Bash(f"git commit -am 'refactor: migrate batch {batch_num} to RepositoryBase'") ``` ## Interaction With Effort Levels - `low` / `medium`: batch size 3–5 (default). - `high`: batch size 5. - `xhigh` (Opus 5): batch size 5 with an extra validation pass per batch — re-read the just-edited files and verify the change matches the migration intent before running tests. Catches LLM-introduced inconsistencies the linter doesn't see. ## Argument `/ork:implement --batch-size 3 migrate all repositories to RepositoryBase` overrides the default when a particularly risky operation warrants smaller steps. ### Commit after each logical milestone — never batch all commits to session end — HIGH ## Commit After Milestone Commit working code after each logical unit of work completes. A "logical unit" is a phase that produces working, buildable output. Never accumulate changes across 3+ phases without committing. ### Problem Claude batches all commits to the end of a session. If the session dies mid-implementation (rate limit, timeout, network), all work is lost. The implement skill runs 10 phases — losing phases 1-7 because the commit was planned for phase 10 is catastrophic. ### Commit Points | After Phase | Commit? | Why | |-------------|---------|-----| | 2. Micro-Plan | Yes | Plan files are valuable context for resume | | 4. Architecture | Yes | Architecture decisions should survive crashes | | 5. Implementation | Yes | The bulk of new code — highest risk of loss | | 6. Integration Verified | Yes | Tests pass, safe checkpoint | | 8. E2E Verified | Yes | Full verification complete | | 10. Reflection | Yes | Final commit with docs and lessons | **Incorrect — one commit after all phases:** ```bash # Phase 1-2: Discovery + Planning (no commit) # Phase 4: Architecture decided (no commit) # Phase 5: 15 files implemented (no commit) # Phase 6: Integration tests pass (no commit) # Phase 8: E2E tests pass (no commit) # --- rate limit hits here --- # All work lost. No commits exist. ``` **Correct — commit at each milestone:** ```bash # After Phase 2: git add .claude/chain/02-plan.json src/docs/plan.md git commit -m "plan: user auth micro-plan and task breakdown" # After Phase 5: git add src/auth/ tests/auth/ git commit -m "feat: implement user auth endpoints and tests" # After Phase 6: git add tests/integration/ git commit -m "test: integration verification for user auth" # After Phase 8: git add tests/e2e/ git commit -m "test: e2e verification for user auth flow" # After Phase 10: git add docs/ .claude/chain/ git commit -m "docs: user auth reflection and lessons learned" ``` ### Commit Message Format ``` : Phase: () Tier: Co-Authored-By: Claude ``` ### Key Rules - Never go more than 2 phases without a commit - Commit even if tests are not yet written — partial progress beats total loss - Use specific `git add <files>` instead of `git add -A` to avoid committing artifacts - If a phase fails, commit the passing phases first, then address the failure - Include phase number in commit messages for traceability during resume - Handoff JSON files (`.claude/chain/*.json`) should be committed alongside code ### Block completion if new code has zero test coverage — tests are mandatory for every implementation — HIGH ## Test Coverage Requirement Every task in Phase 5 must produce both implementation code AND matching tests. The test-generator agent is not optional — it runs in parallel with implementation agents and its output is required before Phase 6. ### Problem Claude often treats tests as a "nice to have" and moves to integration/documentation phases without verifying that test-generator actually produced output. The Phase 9 gate catches this too late. ### Per-Task Enforcement Each Phase 5 task must include a test verification step: ```python # After each implementation agent completes: task_output = TaskOutput(task_id) # Check: does the output include test files? Grep(pattern="describe\\(|it\\(|test\\(|def test_", glob="**/*.test.*") Grep(pattern="def test_|class Test", glob="**/test_*.py") # If 0 matches for new code paths → BLOCK Phase 6 entry ``` **Incorrect — proceed without tests:** ```python # Phase 5: Implementation Agent(subagent_type="ork:backend-system-architect", prompt="Implement user auth endpoints", run_in_background=True) Agent(subagent_type="ork:frontend-ui-developer", prompt="Implement login form", run_in_background=True) # No test-generator agent spawned # Phase 6: "Let's verify integration..." ← no tests exist to run ``` **Correct — tests are parallel and mandatory:** ```python # Phase 5: Implementation + Tests (parallel) Agent(subagent_type="ork:backend-system-architect", prompt="Implement user auth endpoints", run_in_background=True) Agent(subagent_type="ork:frontend-ui-developer", prompt="Implement login form", run_in_background=True) Agent(subagent_type="ork:test-generator", prompt="Generate tests for user auth: unit tests for endpoints, integration tests for auth flow, component tests for login form. Change types: API endpoint + UI component (see Test Requirements Matrix)", run_in_background=True) # GATE: Verify before Phase 6 for agent in [backend, frontend, test_gen]: output = TaskOutput(agent.task_id) if test_file_count == 0: # DO NOT proceed — return to Phase 5 Agent(subagent_type="ork:test-generator", prompt="BLOCKED: No tests found. Generate tests for: {files_created}") ``` ### Change Type to Test Mapping Always reference the Test Requirements Matrix from SKILL.md when spawning test-generator: | Change | Minimum Tests | |--------|--------------| | API endpoint | 1 unit + 1 integration | | DB migration | 1 migration test | | UI component | 1 unit + 1 snapshot | | Business logic | 2 unit tests | ### Key Rules - Spawn test-generator in the same message as implementation agents - Verify test output before advancing to Phase 6 - If test-generator fails, re-run it — do not skip - Include test file paths in the `05-implementation.json` handoff ### Match implementation tier to assessed complexity — never over-engineer a simple task — HIGH ## Tier Validation The tier detected in Step 0 sets a hard ceiling on architecture complexity. Every phase must respect this ceiling — especially Phase 4 (Architecture) and Phase 5 (Implementation). ### Tier Ceilings | Tier | Max Patterns | Max Files | Forbidden | |------|-------------|-----------|-----------| | 1. Interview | Flat files, simple routes | 8-15 | DI containers, message queues, microservices | | 2. Hackathon | Single file if possible | 5-10 | Abstract factories, hexagonal layers | | 3. MVP | MVC monolith | 20-40 | CQRS, event sourcing, k8s manifests | | 4-5. Growth/Enterprise | Full patterns allowed | No limit | None | ### Problem Claude defaults to enterprise-grade patterns regardless of project size. A take-home interview gets hexagonal architecture with ports/adapters when a flat Express app with 3 routes would score higher. **Incorrect — Tier 1 interview with enterprise architecture:** ```python # Detected: Tier 1 (Interview, README says "take-home, 4-hour limit") # Phase 4 agent prompt: Agent(subagent_type="ork:backend-system-architect", prompt="Design hexagonal architecture with DI container, repository pattern, CQRS for read/write separation, and event sourcing for the todo API") # Result: 35 files, 4 abstraction layers for a CRUD app ``` **Correct — Tier 1 interview with appropriate simplicity:** ```python # Detected: Tier 1 (Interview, README says "take-home, 4-hour limit") # Phase 4 agent prompt: Agent(subagent_type="ork:backend-system-architect", prompt="Design a simple flat-file Express app for the todo API. Tier: 1 (Interview). Max 10 files. No DI, no abstractions beyond MVC. Focus: working code, clear tests, clean README.") # Result: 8 files, runs out of the box, easy to review ``` **Validation check — add to Phase 4 handoff:** ```python # In 04-architecture.json handoff: { "tier": 1, "patterns_used": ["flat-routes", "single-db-file"], "tier_ceiling_respected": true, "justification": "Interview project — simplicity scores higher than abstraction" } # If patterns_used includes anything above the tier ceiling, STOP and simplify ``` ### Key Rules - Always pass the detected tier to every subagent prompt explicitly - If a subagent produces output exceeding the tier ceiling, reject and re-run with stricter constraints - When in doubt, under-engineer — simpler code is easier to review and extend - Tier upgrades require explicit user confirmation via `AskUserQuestion` ### Always ExitWorktree after implementation — never leave orphaned worktrees — HIGH ## Worktree Cleanup When the implement skill uses `EnterWorktree` for isolation, it MUST call `ExitWorktree` before completing — regardless of success or failure. Orphaned worktrees block future git operations and leak disk space. ### Problem Claude enters a worktree for isolation but forgets to exit when the implementation finishes, errors out, or gets interrupted. The worktree directory and its lock file persist, causing `git worktree add` failures in the next session. **Incorrect — enter worktree, finish, but never exit:** ```python # Phase 3: Enter worktree EnterWorktree(name="feat-user-auth") # Phase 5: Implementation agents run in worktree Agent(subagent_type="ork:backend-system-architect", prompt="Implement auth...") # Phase 9: Documentation # "Done! Here's what was implemented..." # ← MISSING: ExitWorktree never called # Next session: "fatal: 'feat-user-auth' is already checked out" ``` **Correct — exit worktree in all code paths:** ```python # Phase 3: Enter worktree EnterWorktree(name="feat-user-auth") # Phase 5-8: Implementation, verification, testing... # (all work happens in worktree) # Phase 9: Before documentation, merge and exit Bash("git add -A && git commit -m 'feat: user auth implementation'") ExitWorktree() # Merges back to original branch and removes worktree # Phase 10: Reflection (back in main working tree) ``` **Correct — exit worktree even on failure:** ```python # Phase 3: Enter worktree EnterWorktree(name="feat-user-auth") worktree_active = True # Phase 5: Implementation fails try: Agent(subagent_type="ork:backend-system-architect", prompt="...") except: # STILL clean up the worktree if worktree_active: Bash("git stash") # Save partial work ExitWorktree() worktree_active = False raise # Normal exit path if worktree_active: ExitWorktree() ``` ### Verification After `ExitWorktree`, confirm cleanup: ```bash # Should NOT list the feature worktree git worktree list # Expected: only the main worktree # /path/to/repo abc1234 [main] ``` ### Key Rules - Every `EnterWorktree` must have a matching `ExitWorktree` - Call `ExitWorktree` BEFORE Phase 10 (Reflection) so reflection runs in the main tree - On error or early exit, still call `ExitWorktree` to prevent orphaning - If resuming a session that has an active worktree, check `git worktree list` first - Never assume the worktree will be cleaned up by a future session - Include worktree status in handoff JSON: `"worktree_active": false` after cleanup