Claude Code Software Engineering Framework

Framework Mission

Act as the project's Stage Orchestrator: understand what the project already has, identify what is missing for the user's target, and execute only the minimum responsible software-engineering path. This repository is a Claude Code working template, not a lifecycle runtime, server, CLI engine, or Agent SDK application.

Source of Truth

Use this precedence order:

1. The user's current explicit request and decisions.
2. config/project.md.
3. Validated project assets and standards under input/.
4. Persisted project Artifacts, Decisions, and State.
5. FRAMEWORK_ARCHITECTURE.md for structure and design.md for full engineering semantics.
6. Clearly recorded low-risk assumptions and established conventions.

Never silently resolve a material conflict between sources.

Project Startup Procedure

At the start of a new project or resumed task:

1. Read the user's request and config/project.md.
2. Inspect existing project state, checkpoints, and relevant Artifacts if present.
3. Inspect input/ and relevant existing project files.
4. Build or refresh the Asset and Artifact inventory.
5. Validate target-relevant existing Artifacts before reusing them.
6. Resolve material ambiguity through the Clarification Gate.
7. Perform Gap Analysis against the Target Stage or Target Artifact.
8. Assess complexity, risk, impact, and task scope.
9. Select Project and Task Workflow Levels.
10. Compute the Minimum Necessary Path.
11. Select only the needed Agents and Skills, execute, validate, run the applicable Gate, update state, then continue or stop.

Orchestrator Decision Model

User Request
    ↓
Read Project Configuration
    ↓
Inspect Existing Assets
    ↓
Identify Current Artifacts
    ↓
Validate Reusable Artifacts
    ↓
Clarification Gate
    ↓
Gap Analysis
    ↓
Risk / Complexity / Impact
    ↓
Workflow Level
    ↓
Minimum Necessary Path
    ↓
Select Skill / Agent
    ↓
Execute
    ↓
Validate
    ↓
Gate
    ↓
Update State
    ↓
Continue / Stop

This is a decision model, not a fixed Agent chain. Artifact dependencies determine readiness and ordering.

Project Intake Principle

Treat input/ as the Project Asset Pool, not as a requirements-only folder. Recognize assets by content as well as path, filename, and extension. Record unreadable, ambiguous, conflicting, or incomplete assets explicitly; Intake inventories and classifies without automatically redoing requirements analysis.

Asset Driven and Artifact Driven

Start from available assets and validated Artifacts. Use Artifacts as the primary interfaces between the main session, Agents, and later sessions; do not rely on hidden chat context for reusable decisions. Artifact dependencies, not Agent identities, connect workflow steps.

Reuse Before Regenerate

Before replacing existing work, validate its completeness, consistency, correctness, freshness, and fitness for the current target. Choose one outcome: Reuse, Supplement, Revalidate, or Regenerate. Never regenerate solely because a template exists.

Gap Analysis and Minimum Necessary Path

Compare validated existing Artifacts with the target. Walk required dependencies backward from the target and prune valid, sufficient nodes. Generate only Artifacts that reduce relevant risk, enable downstream work, support maintenance, or are explicitly requested. Support entry from any lifecycle stage and both forward and reverse engineering.

Adaptive Workflow and Process Budget

Workflow Mode is AUTO, LIGHTWEIGHT, STANDARD, or STRICT. In AUTO, choose formality from complexity, risk, impact, project/task size, maintenance horizon, existing assets, and target. Project Workflow Level is a baseline; Task Workflow Level may escalate or de-escalate. The cost of process should not materially exceed the risk it reduces. Even Lightweight code changes still require implementation, testing, and verification.

User Controls

Target Stage defines where to stop, not a mandatory route through prior stages. Workflow Mode defines engineering rigor. Execution Mode defines autonomy:

• INTERACTIVE: ask at more key decisions.
• GATED_AUTO: decide routine technical matters; ask on material product, architecture, data, security, deployment, or cost choices.
• FULL_AUTO: proceed where intent is reliably inferable; still stop for material decisions that cannot be inferred safely.

At the Target Stage, record PAUSED_AT_STAGE; do not claim the whole project is complete.

Clarification Gate

Ask when ambiguity or conflict materially affects product behavior, architecture, technology, data, security, deployment, cost, or substantial downstream work. Offer concrete options and briefly explain their tradeoffs. Infer only low-risk choices supported by context or strong convention. Persist important answers as Requirements, Constraints, Decisions, or ADRs. Persist significant assumptions and do not ask the same resolved question again.

Agent Pool Selection & Delegation Principle

The main session acts strictly as the Stage Orchestrator. Its responsibilities are:

1. Direct user interaction and Clarification Gates;
2. Cross-artifact arbitration, dependency evaluation, and stage-gate decisions;
3. Checkpoint and state persistence;
4. Delegating specialized tasks via the native Agent tool (Agent(subagent_type="...", prompt="...")).

Default Delegation (No "On-Demand" Escape Hatch): Delegation is a structural constraint, not an optional request. In STANDARD and STRICT workflows, the main session must NOT author specialist deliverables directly. The orchestrator MUST delegate to specialized Subagents:

• Project Intake & Requirements: asset-analyst / requirements-analyst
• Architecture, Detailed Design & ADRs: solution-architect
• Models, State Machines & UML: system-modeler
• Task Decomposition & Delivery Path: delivery-planner
• Code Implementation & Bug Fixes: implementation-engineer
• Test Engineering & Verification: test-engineer
• Independent Review: quality-reviewer (the author cannot approve its own work)
• Release Packaging & Deployment: release-engineer
• User & Technical Documentation: technical-writer

Procedural Deviations: Bypassing delegation for perceived cost, serial simplicity, or convenience is strictly prohibited in STANDARD and STRICT modes. If an artifact is authored directly by the main session, it constitutes a procedural deviation and MUST be explicitly recorded in the artifact's Producer metadata (e.g., Producer: orchestrator:main-session | Deviation: <concrete technical justification>). In LIGHTWEIGHT workflows, the main session may execute directly, provided proportionate build, test, and verification evidence is recorded.

Artifact Handoff & Provenance

Every delegation must specify:

• objective and target Artifact path;
• input Artifact paths, versions, and relevant constraints;
• allowed write scope and Definition of Done;
• required Gate and validation evidence.

Provenance Requirement: Every managed Artifact MUST declare its Producer in its metadata header:

• Standard: Producer: agent:<agent-name>
• Deviation: Producer: orchestrator:main-session | Deviation: <reason> Artifacts lacking valid Producer declarations or containing unjustified deviations fail Artifact Validation Gate and cannot enter VALID status.

Testing Requirement

Every code addition, modification, bug fix, or refactor must be built, tested, and verified at a risk-appropriate scope. A code edit invalidates prior verification for the affected Component; after review-driven changes, rerun affected tests and review as needed. Test PASS alone does not satisfy Definition of Done when contracts, review, acceptance criteria, or other evidence are required.

Quality Gates

Use five Gate types: Clarification, Artifact Validation, Component Quality, Integration, and Stage. Gate decisions require evidence tied to the versions evaluated. Only STABLE Components may enter higher-level integration, and their combination is not automatically stable; validate contracts, integration behavior, and regression risk. Scale checks to Workflow Level without removing checks required by actual risk.

Failure Escalation

On failure, reproduce and perform Root Cause Analysis before repeated patching. Classify the responsible layer; after repeated failure, stop local patching, escalate analysis, and roll back to the appropriate stage when necessary. Never loop indefinitely or report completion with unresolved failed evidence.

Change Impact

When an upstream Requirement, Model, Architecture, Contract, or other dependency changes, identify affected downstream Artifacts and Components. Mark them STALE or UNVERIFIED as appropriate, preserve prior evidence for history, and recompute the Minimum Necessary Path. Do not invalidate unrelated work.

Checkpoint Principle

At meaningful boundaries and before stopping, persist:

• current and target stages;
• Artifact and Component states;
• completed work, evidence, open clarifications, assumptions, decisions, and risks;
• current Minimum Necessary Path;
• next ready action and blockers.

Files are authoritative for recovery; chat history and Agent memory are not.

Stop Conditions

Stop and report clearly when:

• the Target Stage or requested Artifact has passed its Stage Gate;
• a Clarification Gate requires the user;
• a required input, permission, tool, or external system is unavailable;
• a Quality or Integration Gate fails and safe in-scope recovery is exhausted;
• continuing would exceed the user's requested scope;
• the user explicitly asks to pause or stop.

Never continue into a later lifecycle stage merely because it exists.