Implementation Runner

Implementation Runner

Inputs

• analysisContext.request.userMessage
• analysisContext.request.taskType
• analysisContext.decisions.skillChain
• analysisContext.repo.openFiles
• analysisContext.codeReviewGraph.contextSummary
• analysisContext.codeReviewGraph.impactSummary
• analysisContext.codeReviewGraph.warnings
• analysisContext.artifacts.workflowGuidePath
• analysisContext.artifacts.designGuidePath
• analysisContext.artifacts.glossaryGuidePath
• analysisContext.artifacts.dailyGuidePath
• analysisContext.artifacts.testGuidePath
• analysisContext.artifacts.analysisIndexPath / analysisRoot
• analysisContext.artifacts.contextDocPath (if present)
• analysisContext.artifacts.planPath / taskSliceGlob (if present)
• analysisContext.artifacts.sprintContractPath (when execution bridge is required)
• analysisContext.artifacts.scorecardPath (when execution bridge is required)

Procedure

Step 0: Project Reference Docs

Before code edits, load the applicable project reference docs when they exist:

• workflow/README.md for branch/worktree/process rules
• docs/design/README.md for shared UI and pattern rules
• docs/glossary/README.md for canonical naming
• docs/daily/README.md for logging expectations
• TEST_GUIDE.md for verification scope expectations
• relevant docs/analysis/*.md when the target area already has prior analysis

Rules:

• Prefer these docs over ad-hoc assumptions for naming, structure, testing, and workflow behavior.
• If a relevant doc is missing, record the absence in notes and continue with the best available contract instead of inventing policy.

Step 0.0: Codex Rule References

When the active runtime is Codex, read and apply the relevant rule files explicitly instead of assuming recursive rule loading:

• .claude/rules/coding-style.md
• .claude/rules/scope-confirmation.md
• .claude/rules/refactoring-guidelines.md
• .claude/rules/testing.md
• .claude/rules/security.md
• .claude/rules/quality.md
• .claude/rules/communication.md
• .claude/rules/output-format.md

Step 0.1: Execution Bridge Setup

Before code edits, determine whether the current run requires a slice-level sprint contract.

Require contract setup when:

• executionPlane == product_project
• and complexity != simple or artifacts.sprintContractPath is already populated

If required:

1. Resolve the active slice from PLAN.md, tasks/*.md, or current notes
2. Create or refresh SPRINT_CONTRACT.md
3. Record:
   • round goal
   • explicit non-goals
   • done checks
   • evaluator focus
   • expected evidence
   • policy anchors (always-loaded rules, active workspace contract, verification contract, round-specific guides)
   • objective score checklist and target
4. If a safe contract cannot be derived, stop and return planning notes instead of guessing in code

Result:

signals.sprintContractReady: true | false
readiness.executionReady: true | false
notes:
  - "sprint-contract: ready, path=..."
  - "scorecard: ready, path=..."

Step 0.2: Review / Closeout Preconditions

When the run is attached to a phase execution bridge:

• treat code review as a required workflow step for code-changing slices, not as optional polish
• do not leave QA_REPORT.md with Review completed: no if the slice is about to claim clean_finish
• do not leave HANDOFF.md, review checkpoint fields, or finish-closeout bullets in placeholder form for a closing slice
• if review or finish evidence is missing, record the gap and keep the slice in retry/remediation flow instead of pretending implementation is done

Step 0.3: Code Review Graph Target Narrowing

Before code edits, apply docs/public/guidelines/code-review-graph-workflow.md when the task requires code structure analysis:

• Read analysisContext.codeReviewGraph.contextSummary and impactSummary before opening broad file sets.
• If the graph is not_built or stale and code structure analysis is needed for this stage, use the MCP build/update path or CLI fallback within the current request scope.
• Use the summary to limit target files, likely dependencies, and impact radius.
• If CRG is unavailable, record a warning and continue with normal bounded file inspection.
• Do not paste raw graph output or .code-review-graph/ contents into implementation notes.

Step 1: Test Environment Detection

Before starting implementation, check if the target project has a test environment:

testEnvironmentCheck:
  # Check for test config files
  configFiles:
    - "jest.config.*"
    - "vitest.config.*"
    - "playwright.config.*"
    - "pytest.ini"
    - "pyproject.toml [tool.pytest]"
  # Check package.json scripts.test
  packageJson: "scripts.test != default error message"
  # Check for existing test files
  testFiles: "**/*.test.* | **/*.spec.* | __tests__/ | tests/"

result:
  signals.testEnvironmentDetected: true | false
  signals.testFramework: "{detected}" | null

When testEnvironmentDetected = false, skip test co-creation (Step 5) with warning.

For All Tasks

1. Check requirements, context, and SPRINT_CONTRACT.md when present.
2. Check project reference docs relevant to the change when present.
3. Define change scope from the active slice and implement.
4. Record changed files and key change summary.
5. Update implementation completion in analysisContext.
6. Write tests (if testEnvironmentDetected = true, see Step 5).

For Refactor Tasks (taskType == refactor)

Reference: .claude/rules/scope-confirmation.md, .claude/rules/refactoring-guidelines.md

1. Scope Confirmation (Required) Before starting:

• Confirm IN SCOPE packages/modules
• Confirm OUT OF SCOPE items (API routes, DB schemas, etc.)
• If scope unclear, ask user for clarification

2. Baseline Error Capture

npm run build 2>&1 | tee /tmp/baseline-errors.log

3. Phased Execution For complex refactoring, break into phases:

1. Complete each phase fully
2. Run build verification after each phase:

   npx tsc --noEmit --pretty
   

3. Report pass/fail status
4. Proceed only when build passes

4. Error Separation

• Document pre-existing errors (from baseline)
• Document only NEW errors introduced by refactoring

5. Scope Lock If need to touch OUT OF SCOPE items:

• Stop and ask user for permission
• Record decision in notes

6. Self-Healing Loop (자동 빌드 오류 수정) When build fails during refactoring:

retryCount = 0
maxRetries = 2

while (build fails AND retryCount < maxRetries):
  1. Analyze build error output
  2. Apply fix (reference: build-error-resolver patterns)
  3. Re-run build verification
  4. retryCount++

if (still failing after maxRetries):
  - Stop and report to user
  - List all attempted fixes
  - Ask for intervention

This enables autonomous error resolution without user intervention for common issues.

Step 5: Test Co-Creation

Only when signals.testEnvironmentDetected = true

When implementing features, write tests alongside code changes:

testCoCreation:
  # 1. Unit tests for new/changed functions
  unitTests:
    scope: "Each new or significantly modified function"
    naming: "{Component}.test.ts(x) or {module}.test.ts"
    minimum: 1 per feature

  # 2. Integration tests for user-facing flows
  integrationTests:
    scope: "Each new API endpoint or user flow"
    naming: "{feature}.integration.test.ts"
    minimum: 1 per flow (when applicable)

  # 3. Bug fix reproduction tests
  bugfixTests:
    scope: "Each bug being fixed"
    naming: "Include 'regression' or bug ID in test name"
    requirement: "Write reproduction test BEFORE fixing"

When test env NOT detected:

action:
  - Log: "⚠️ No test environment. Skipping test co-creation."
  - Set signals.testsWritten = false
  - Continue to output

Output (patch)

signals.implementationComplete: true
signals.testEnvironmentDetected: true | false
signals.testsWritten: true | false
signals.sprintContractReady: true | false
signals.selfHealingAttempts: 2  # Number of auto-fix attempts
repo.changedFiles:
  - src/...
  - src/__tests__/...  # Test files included
notes:
  - "sprint-contract: ready, path=..."
  - "scorecard: ready, path=..."
  - "implementation: complete, changed_files=3, tests_written=2"
  - "refactor: scope_confirmed=true, phases=3, build_status=pass"
  - "self-healing: attempts=1, fixed=TS2339"  # For auto-fixed errors
  - "test-env: detected=true, framework=vitest"  # Or "test-env: not_detected"

Rules

• Do not call other skills/subagents.
• If failed or deferred, record the reason in notes.
• When execution bridge is required, do not skip SPRINT_CONTRACT.md.
• When execution bridge is required, do not skip SCORECARD.md.
• For refactor tasks: always confirm scope before starting.
• Self-healing: max 2 retry attempts per phase before asking user.
• Test co-creation: When test environment exists, implementation without tests is incomplete.