architecture.md

Architecture

Layers

• Framework project: CLI, adapters, prompts, launchers, validators, docs, templates, Copilot custom agents, and Jira story-source integration through Atlassian Rovo MCP.
• Target repo: codebase, local AGENTS.md, and the minimal .wi/ artifact set.

Layer interaction

sequenceDiagram
    participant Ticket as Story Source
    participant AWF as AWF CLI
    participant Repo as Target Repo
    participant Agent as Phase Agent or CLI
    participant Human as Human Reviewer

    Ticket->>AWF: start-story
    AWF->>Repo: write story.json
    alt story is ambiguous
        AWF->>Repo: clarification.json = requested
        AWF->>AWF: pause for clarify-story
    else story is stable
        AWF->>Repo: plan -> tasks.json + acceptance.json
    end
    AWF->>Repo: run-next -> runtime/task.json
    Agent->>Repo: implement task changes
    AWF->>Repo: continue -> orientation.json
    AWF->>Repo: review -> review log / corrective tasks
    AWF->>Human: request review when enabled
    Human->>AWF: approve or reject
    AWF->>Repo: verify-story or return to planning/implementation

Loading

Why this architecture is useful

The separation between framework and target repo is one of the main benefits of the solution.

It means:

• the workflow logic is implemented once and reused everywhere
• target repos stay small and repo-specific
• AI process state is durable without embedding framework code into every application repo
• teams can standardize delivery behavior without flattening repo-level autonomy

Artifact model

Required repo artifacts:

• .wi/config.json
• .wi/story.json
• .wi/intake-context.json
• .wi/clarification.json
• .wi/tasks.json
• .wi/acceptance.json
• .wi/state.json
• .wi/blockers.json
• .wi/human-review.json
• .wi/runtime/task.json
• .wi/runtime/orientation.json
• .wi/logs/progress.ndjson
• .wi/logs/review.ndjson
• .wi/README.md

Why these artifacts matter

Each artifact has a distinct job:

• story.json preserves intent
• intake-context.json preserves the story source and any design or context inputs so later clarification passes stay grounded
• clarification.json preserves the latest blocking intake questions before planning
• tasks.json preserves execution slicing
• acceptance.json preserves the coverage contract
• runtime/task.json keeps the active session small and focused by carrying the current story slice, referenced AC text, and execution contract
• runtime/orientation.json keeps continuity without transcript replay and stays the source of truth for the full handoff state
• human-review.json holds only the latest optional human decision
• state.json, logs, and blockers make progress auditable

Together they provide a lightweight but durable operational memory for the story, with the task packet pointing to deeper artifacts instead of re-embedding them wholesale.

Runtime contract

• run-next selects exactly one eligible task and creates the runtime packet.
• continue records the outcome, refreshes orientation, optionally auto-commits the verified task, and prepares the next task when possible.
• review evaluates AC coverage and can append corrective tasks.
• verify-story gates completion on task state, AC state, verification commands, blockers, and optional human approval.
• run-supervised advances the workflow automatically until it reaches a safe supervision boundary.
• start-story can normalize either a local Markdown file or a Jira issue URL into .wi/story.json and request clarification when the story is still ambiguous.
• clarify-story answers the open intake questions and reruns the planning-readiness gate.

Phase routing value

The phase_execution contract in .wi/config.json lets you choose which CLI, model, and Copilot custom agent should own each phase.

That matters because it lets you:

• use the best tool for the job instead of forcing one model across the whole lifecycle
• keep routing decisions explicit and reviewable
• evolve model strategy without changing the artifact contract