Factory Mission

factory-mission

In a factory run — read this first

When ADLC_RUN_ID is set, the workflow engine runs this skill unattended as its execute step, and the completion gate follows it. Do exactly this:

1. The mission is the run's issue. Take it from --issue <ref> in the arguments; when that is missing or empty, use ADLC_ISSUE_REF. With neither, do not ask: write {"conclusion":"blocked: factory run without an issue"} into ADLC_STEP_OUTPUT and return.
2. Run the mission for that issue end to end (Phases 0–6 below): brief, test (RED), code (GREEN), converge, then open or reuse the draft code MR/PR in the repository the change belongs to.
3. Before you return, always: write mr_url (the code MR/PR you opened or reused) and a one-line conclusion into ADLC_STEP_OUTPUT — one flat JSON object of string values; keep any keys already in the file. The engine links mr_url at the completion gate. Do this whatever the outcome; with no MR, write only the conclusion.
4. Never ask a question or wait for an answer. The completion gate after this step is the approval; a question here ends the step with nothing implemented.

In a local session — you answer the gates

When ADLC_RUN_ID is not set, a person is in this session, and nothing else will answer a gate. The agentic-container runtime that relays gates to Slack exists only in a runner pod.

1. A paused run is your turn, not the end of the mission. When adlc-cli workflow run or resume exits with the run paused at a gate (run_paused, status: paused in adlc-cli workflow state show <run_id>), ask the person the gate's question and options. Then run adlc-cli workflow resume <run_id> --input <verdict_input>=<answer> and keep going. Never end your turn on a paused run that nobody was asked about.
2. Every gate that approves MRs is followed by a step that opens them. A gate whose message promises MRs/PRs is followed by a publish step: run-branch.sh and open-mr.sh for each repository the change touches, writing mr_url (mr_urls for more than one). Only then comes the write-back step, so the completion comment links real MRs. A gate with nothing after it to act on its answer is a plan defect; fix the plan before you start the run.
3. Before ending your turn, the run is completed, failed or aborted, or it is paused at a gate the person has been asked about.

What this skill does

factory-mission is the execution-harness orchestrator of the software factory. It takes a feature description, structures it into a Mission Brief (goal, constraints, non-goals, success criteria), generates an ordered step list, and executes those steps via sequential subagent runs.

It implements the following key factory platform capabilities:

1. Universal Skill Routing: Decoupled step dispatching. It scans installed skills and hands the inventory to subagents (the model picks which tool fits the step).
2. Tracker-Agnostic Integration (references/tracker-integration.md): When invoked with --issue <ref>, it pulls ticket context, respects automation/dispatch labels (autonomous/supervised), and writes back status comments + iteration logs.
3. Inter-Agent Comment Bus (references/tracker-integration.md §Inter-Agent Comment Bus): When tracker-integrated, each step's terminal output (decisions, findings, artifact references — never drafts) is published as a structured comment on the PR/MR/issue. The next step reads previous markers before starting. This is the durable inter-agent memory that survives session boundaries, runtime switches, and pod crashes. Drafts stay on local disk.
4. Self-Contained Worker Brief: The Mission Brief is persisted to .adlc/workflows/runs/<run_id>/brief.md as a draft. Resumed runs and cross-runtime workers read it from disk — no session-context dependency.
5. Worktree Isolation: Each run gets its own git worktree. Never touches the user's main checkout. Cleaned up on exit (retained if unsaved work).
6. Lease-Based Liveness: The state file carries a renewable lease with heartbeat + TTL. Resume can distinguish live, stale, and completed runs.
7. Stall Detection: After dispatching a subagent, observable progress is checked at a configurable window (default 20 min). A hung agent that passes the circuit breaker is detected and killed.
8. Lane-Based Dispatch (references/lanes.md): Steps can run on different lanes — inline (this session), agent (fresh session of same CLI for maker/checker separation), or cli:<runtime> (optional cross-vendor). The agent lane is the default for unattended stages.
9. Scratchpad Tools: Subagents share named, run-private scratchpads (.adlc/workflows/runs/<run_id>/scratchpads/<name>.txt) to compile notes, drafts, and reviews incrementally before publishing.
10. Workflow Memory & Self-Improvement: Persistent JSONL database (.adlc/workflows/memory.jsonl, workspace-global) stores learnings across runs. factory-learn periodically runs retrospectives to prune/weight memories.
11. Hierarchical Context Parameters: Workflows and agents reference parameters as {{params.<key>}}, resolved from most specific to least specific: agent < workflow < repository < project < default.
12. Decoupled Test/Code Separation: Test-first build with mechanical gates lives in mission-implement; converging judgement in mission-verify.

When to use

• "Build this feature end to end" inside a factory-enabled team.
• You want an execution loop with a circuit breaker, score-regression checking, and a robust resume mechanism (factory-mission --resume).
• You want to run autonomously against a ticket queue.

When NOT to use:

• For non-factory standalone projects (run adlc-cli workflow run <workflow.yml> — the CLI engine, shared run state).
• Trivial 1-line changes (do them directly).

Process

factory-mission executes in alignment with the shared executor contract (references/executor.md) and the tracker-agnostic layer (references/tracker-integration.md).

Phase 0 to 4: Setup & Compilation

1. Read the run's mission.yml (.adlc/workflows/runs/<run_id>/mission.yml). Resolve execution and supervision.
2. If --issue <ref> is specified (in a factory run, ADLC_ISSUE_REF when it is not):
   • Discover credentials and MCP/CLI tools (references/tracker-integration.md).
   • Pull the issue content as the primary Brief description.
   • Read the labels. If dispatch is interactive or gating is human-required -> HALT execution (hand back to interactive session).
   • Dependency hard gate (Operation 12): read the issue's **Depends on** line, resolve each dependency's state via the connector, and refuse when any dependency is still open (only closed / cancelled count complete — spec-gated does NOT satisfy the gate). On refusal: publish a blocked: dependency-gate comment naming the blocking issue(s), set the issue's lifecycle label back to spec-gated, release the lease (ADLC_STEP_OUTPUT conclusion blocked: dependency-gate on <refs>), and return without touching worktree, code, or executor. When the tracker exposes native blocked_by/blocking relations (GitLab issue links, Linear/Jira relations), use them in addition to the brief's Depends-on line — a Blocked/blocked-by signal from the tracker also triggers the gate.
   • The comment bus is active for this run — step outputs will be published as marker comments on the PR/MR/issue.
3. If no issue (outside a factory run): read spec description from arguments. The comment bus is inactive — steps communicate through local files only.
4. Structure the Mission Brief (Goal, Constraints, Non-Goals, Success Criteria). The Brief is a draft — not published to the comment bus.
5. Resolve the framework lane (framework: in mission.yml → detect-framework.sh / detect-framework.ps1, frozen precedence: override → git-dated usage evidence → installed packs → embedded default) and disclose the resolved lane plus its evidence in the run brief (**Framework lane:** <lane> (<evidence>)).
6. Resolve hierarchical Context Parameters from agent < workflow < repository < project < default and embed the frozen value map in the brief.
7. Generate the step list based on route classification (spec, change, quick). Each step declares output_type (draft/decision/findings/artifact-ref) and reads_from (markers or local paths) per the executor contract.

Team index fallback: when no team record-class index was injected at session start, read the binding records directly from docs/adlc/memory/ (dual-read order: docs/adlc/memory first, legacy .adlc/memory fallback) and state that fallback in one line. Never block on the missing injection.

Lifecycle DAG & Step Resolution

factory-mission resolves each lifecycle step to the mission-* skill that owns it. Step order, inputs, and outputs follow the table; the owning skills define the discipline.

A SPEC_CORRECTION_NEEDED verdict routes to the owning clarify gate (mission-specify), never to code.

Boundary

factory-mission owns the execution harness: the worktree, the lease, tracker integration (issue intake, the comment bus, completion write-back), and the draft code MR. It never owns spec content, tests, code, or verdicts — each step's output belongs to the mission-* skill that produced it. Dispatch names phases, not commands: every lifecycle step resolves through the table above.

Shared Executor Overrides

Knobs specific to a mission run, read from mission.yml (the policy home for execution and supervision):

1. Supervision: the run's supervision mode — unattended runs never ask a question.
2. Quality threshold: quality_threshold travels in as a converge input owned by mission-verify; the orchestrator carries it, never applies it.
3. Test/code split: selected per run — whether the build dispatches separate test and code steps.

Phase 6: Completion & Write-Back

1. If tracker-integrated: read all marker comments from the PR/MR/issue to compile the audit trail (converge decisions, test findings, implement artifact references, convergence history).
2. Close the shared run: final adlc-cli workflow state advance <run_id> --step <last> --status completed (the run dir is the durable archive; no separate move).
3. Write per-implement logs to iterations.md.
4. If tracker-integrated:
   • Post completion summary as a ticket comment (marker: factory-mission:status=completed:run=<run_id>).
   • Transition lifecycle label from executing to validation (or done if merged).
   • Stamp agent-authored on opened PRs.
   • In a factory run, write the code MR/PR URL as mr_url into ADLC_STEP_OUTPUT (see "In a factory run" above).
   • Defer PR merge to code-owner approval (never auto-merge without approval).
5. Output the complete audit summary.