Repository Production Workflow
Relevant source files
The following files were used as context for generating this wiki page:
The Repository Production Workflow orchestrates production repository changes from initial context gathering through final review and delivery. It enforces a mandatory sequence of engineering phases to ensure code quality, behavioral verification, and architectural alignment. This system maintains workflow continuity through a repository-scoped SQLite event ledger that records transitions, logical evidence, and phase status.
Sources: skills/repo-production-workflow/SKILL.md:1-10, skills/repo-production-workflow/WORKFLOW-MAP.md:30-40
Workflow Architecture and Data Flow
The system operates as a state machine where transitions are guarded by specific evidence requirements. The following diagram illustrates the high-level path from task inception to delivery.
The workflow map defines the transition rules between engineering phases.
Sources: skills/repo-production-workflow/WORKFLOW-MAP.md:5-28, CLAUDE.md:195-205
Workflow State Persistence
The workflow uses a repository-scoped SQLite event ledger to track progress. This ledger stores:
- Accepted Transitions: Logical steps taken in the workflow.
- Logical Evidence: Links to specific documents or test results (e.g., Preflight JSON, TDD results).
- Phase Status: The current stage of the implementation (e.g.,
gitnexus,red,green,verify). - Active Projection: A disposable summary used for quick status checks and hook automation.
Sources: skills/repo-production-workflow/SKILL.md:20-25, skills/repo-production-workflow/WORKFLOW-MAP.md:30-38
Mandatory Execution Phases
1. Initialization and Context
Every production pass begins with a stable task slug and an intent statement. The Repo Context Forge establishes the initial target surface and records graph evidence.
- Command:
workflow.py begin --slug <task> --intent <text> - Artifact: The recorded intent serves as the contract for the entire pass.
Sources: skills/repo-production-workflow/SKILL.md:12-25, skills/repo-production-workflow/SKILL.md:37-45
2. Preflight and Advisory
Before any code is modified, the agent must perform a scope check and a formal preflight.
- Codex Advisor: Evaluates design and scope questions, producing material behavioral findings.
- Production Preflight: Generates a structured document including an
affectedSurface,authoritativeContract, and abehaviorMap. - Refusal Logic:
record-preflightrefuses documents with empty text sections or unresolvedopenQuestions.
Sources: skills/repo-production-workflow/SKILL.md:65-90, skills/production-preflight/SKILL.md:79-95
3. Test-Driven Development (TDD)
The workflow mandates behavior-specific proof through real production seams.
- RED Phase: A failing test that reproduces the intended behavior or symptom must exist before production edits.
- GREEN Phase: Implementation edits are verified against the mapped RED items.
- Mock Ban: Mocks, stubs, or test-only adapters are strictly prohibited; proof must cross the real production Interface.
Sources: skills/repo-production-workflow/SKILL.md:92-110, CLAUDE.md:20-25, skills/tdd/SKILL.md:5-15
4. Verification and Review
After implementation, the candidate tree undergoes rigorous verification and multi-stage review.
- Verification: Executes the changed-behavior RED/GREEN, linting, type-checking, and the typed
quality-gate. - Delegate Review: A fresh-context sub-agent (pinned to
claude-fable-5-1) performs a Standards/Spec review. - Final Advisor Review: Judges the candidate, the delegate review, and the lead's dispositions against the original intent.
Sources: skills/repo-production-workflow/SKILL.md:135-155, skills/repo-production-workflow/SKILL.md:162-180
Command Interface Summary
The workflow.py script is the primary interface for managing workflow state.
| Command | Purpose | Required Evidence/Inputs |
|---|---|---|
begin | Starts a new workflow instance | --slug, --intent |
status | Returns schemaVersion: 1 JSON projection | N/A |
record-preflight | Records preflight and behavior map | JSON file with 13 text sections |
tdd | Transitions to RED/GREEN status | --phase, --behavior-id, <cmd> |
tdd-map | Updates the map after GREEN results | sourceBehaviorId, items |
verify | Records generic or quality-gate verification | <command> or --kind quality-gate |
record-review | Stores delegate findings and dispositions | review.json, workflowId |
complete | Closes the workflow as terminal | All items GREEN; manifest match |
Sources: skills/repo-production-workflow/SKILL.md:12-20, skills/repo-production-workflow/WORKFLOW-MAP.md:41-52
Completion Requirements
The complete command performs a final transaction-bound audit. It refuses to close the workflow unless:
- Map Integrity: Every contract item is GREEN, baseline, or withdrawn.
- Evidence Binding: Preflight, TDD, and verification each carry valid producer evidence references.
- Review Closure: Material findings from all review stages are dispositioned.
- Manifest Match: The working tree matches the manifest recorded during the lead review.
Sources: skills/repo-production-workflow/SKILL.md:200-215, skills/repo-production-workflow/WORKFLOW-MAP.md:100-115
Conclusion
The Repository Production Workflow provides a rigid structure for repository-changing work, shifting the focus from individual tool calls to a governed execution sequence. By enforcing evidence recording and multi-agent reviews, the system ensures that every production change is traceable to its original intent and verified through real-seam testing.
Sources: skills/repo-production-workflow/SKILL.md:235-240, skills/repo-production-workflow/WORKFLOW-MAP.md:185-195