Triple-C/container/mission-control/.claude/skills/init-project/templates/ARTIFACTS-files.md

Artifact System: Filesystem

This project stores Flight Control artifacts as markdown files in the repository.

Directory Structure

{project}/
├── missions/
│   └── {NN}-{mission-slug}/
│       ├── mission.md
│       ├── mission-debrief.md
│       └── flights/
│           └── {NN}-{flight-slug}/
│               ├── flight.md
│               ├── flight-log.md
│               ├── flight-briefing.md
│               ├── flight-debrief.md
│               └── legs/
│                   └── {NN}-{leg-slug}.md
└── maintenance/
    └── {YYYY-MM-DD}.md

Naming Conventions

• Slugs: Lowercase, kebab-case, derived from title (e.g., "User Authentication" → user-authentication)
• Sequence numbers: Missions, flights, and legs use two-digit prefixes (01, 02, etc.) for ordering

---

Core Artifacts

Mission

Property	Value
Location	missions/{NN}-{slug}/mission.md
Created	During mission planning
Updated	Until status changes to active

Format:

# Mission: {Title}

**Status**: planning | active | completed | aborted

## Outcome
What success looks like in human terms.

## Context
Why this mission matters now. Background information.

## Success Criteria
- [ ] Criterion 1 (observable, binary)
- [ ] Criterion 2
- [ ] Criterion 3

## Stakeholders
Who cares about this outcome and why.

## Constraints
Non-negotiable boundaries.

## Environment Requirements
- Development environment (devcontainer, local toolchain, cloud IDE)
- Runtime requirements (GUI, audio hardware, network access)
- Special tooling (Docker, specific CLI versions)

## Open Questions
Unknowns that need resolution during execution.

## Known Issues
Emergent blockers and issues discovered during execution. Add items here as flights surface problems that affect the broader mission — things not anticipated during planning but visible at the mission level.

- [ ] {Issue description} — discovered in Flight {N}, affects {scope}

## Flights

> **Note:** These are tentative suggestions, not commitments. Flights are planned and created one at a time as work progresses. This list will evolve based on discoveries during implementation.

- [ ] Flight 1: {description}
- [ ] Flight 2: {description}
- [ ] Flight N *(optional)*: Alignment — vibe coding session for creative collaboration and hands-on adjustments

---

Flight

Property	Value
Location	missions/{mission}/flights/{NN}-{slug}/flight.md
Created	During flight planning
Updated	Until status changes to in-flight

Format:

# Flight: {Title}

**Status**: planning | ready | in-flight | landed | completed | aborted
**Mission**: [{Mission Title}](../../mission.md)

## Contributing to Criteria
- [ ] {Relevant success criterion 1}
- [ ] {Relevant success criterion 2}

---

## Pre-Flight

### Objective
What this flight accomplishes (one paragraph).

### Open Questions
- [ ] Question needing resolution
- [x] Resolved question → see Design Decisions

### Design Decisions

**{Decision Title}**: {Choice made}
- Rationale: Why this choice
- Trade-off: What we're giving up

### Prerequisites
- [ ] {What must be true before execution}

### Pre-Flight Checklist
- [ ] All open questions resolved
- [ ] Design decisions documented
- [ ] Prerequisites verified
- [ ] Validation approach defined
- [ ] Legs defined

---

## In-Flight

### Technical Approach
How the objective will be achieved.

### Checkpoints
- [ ] {Milestone 1}
- [ ] {Milestone 2}

### Adaptation Criteria

**Divert if**:
- {Condition requiring re-planning}

**Acceptable variations**:
- {Minor changes that don't require diversion}

### Legs

> **Note:** These are tentative suggestions, not commitments. Legs are planned and created one at a time as the flight progresses. This list will evolve based on discoveries during implementation.

- [ ] `{leg-slug}` - {Brief description}
- [ ] `{leg-slug}` - {Brief description}
- [ ] `uat-and-alignment` *(optional)* - Guided UAT session with iterative fixes

---

## Post-Flight

### Completion Checklist
- [ ] All legs completed
- [ ] Code merged
- [ ] Tests passing
- [ ] Documentation updated

### Verification
How to confirm the flight achieved its objective.

---

Leg

Property	Value
Location	missions/{mission}/flights/{flight}/legs/{NN}-{slug}.md
Created	Before leg execution
Updated	Never once in-flight (immutable)

Format:

# Leg: {slug}

**Status**: planning | ready | in-flight | landed | completed | aborted
**Flight**: [{Flight Title}](../flight.md)

## Objective
Single sentence: what this leg accomplishes.

## Context
- Relevant design decisions from the flight
- How this fits into the broader technical approach
- Key learnings from prior legs (from flight log)

## Inputs
What exists before this leg runs:
- Files that must exist
- State that must be true

## Outputs
What exists after this leg completes:
- Files created or modified
- State changes

## Acceptance Criteria
- [ ] Criterion 1 (specific, observable)
- [ ] Criterion 2
- [ ] Criterion 3

## Verification Steps
How to confirm each criterion is met:
- {Command or manual check for criterion 1}
- {Command or manual check for criterion 2}

## Implementation Guidance

1. **{First step}**
   - Details about what to do

2. **{Second step}**
   - Details

## Edge Cases
- **{Edge case 1}**: How to handle

## Files Affected
- `path/to/file.ext` - {What changes}

---

## Post-Completion Checklist

**Complete ALL steps before signaling `[COMPLETE:leg]`:**

- [ ] All acceptance criteria verified
- [ ] Tests passing
- [ ] Update flight-log.md with leg progress entry
- [ ] Set this leg's status to `completed` (in this file's header)
- [ ] Check off this leg in flight.md
- [ ] If final leg of flight:
  - [ ] Update flight.md status to `landed`
  - [ ] Check off flight in mission.md
- [ ] Commit all changes together (code + artifacts)

---

Supporting Artifacts

Flight Log

Property	Value
Location	missions/{mission}/flights/{flight}/flight-log.md
Created	When flight is created
Updated	Continuously during execution (append-only)

Format:

# Flight Log: {Flight Title}

**Flight**: [{Flight Title}](flight.md)

## Summary
Brief overview of execution status and key outcomes.

---

## Leg Progress

### {Leg Name}
**Status**: completed | landed | in-flight | aborted
**Started**: {timestamp}
**Completed**: {timestamp}

#### Changes Made
- {Summary of what was implemented}

#### Notes
{Observations during execution}

---

## Decisions
Runtime decisions not in original plan.

### {Decision Title}
**Context**: Why needed
**Decision**: What was chosen
**Impact**: Effect on flight or future legs

---

## Deviations
Departures from planned approach.

### {Deviation Title}
**Planned**: What the flight specified
**Actual**: What was done instead
**Reason**: Why the deviation was necessary

---

## Anomalies
Unexpected issues encountered.

### {Anomaly Title}
**Observed**: What happened
**Severity**: blocking | degraded | cosmetic
**Resolution**: How handled or "unresolved"

---

## Session Notes
Chronological notes from work sessions.

---

Flight Briefing

Property	Value
Location	missions/{mission}/flights/{flight}/flight-briefing.md
Created	Before flight execution begins
Purpose	Pre-flight summary for crew alignment

Format:

# Flight Briefing: {Flight Title}

**Date**: {briefing date}
**Flight**: [{Flight Title}](flight.md)
**Status**: Flight is ready for execution

## Mission Context
{Brief reminder of mission outcome and how this flight contributes}

## Objective
{What this flight will accomplish}

## Key Decisions
{Summary of critical design decisions crew should know}

## Risks and Mitigations
| Risk | Mitigation |
|------|------------|
| {risk} | {mitigation} |

## Legs Overview
1. `{leg-slug}` - {description} - {estimated complexity}
2. `{leg-slug}` - {description} - {estimated complexity}

## Environment Requirements
{Any special setup needed before starting}

## Success Criteria
{How we'll know the flight succeeded}

---

Flight Debrief

Property	Value
Location	missions/{mission}/flights/{flight}/flight-debrief.md
Created	After flight lands or diverts
Purpose	Post-flight analysis and lessons learned

Format:

# Flight Debrief: {Flight Title}

**Date**: {debrief date}
**Flight**: [{Flight Title}](flight.md)
**Status**: {landed | aborted}
**Duration**: {start} - {end}
**Legs Completed**: {X of Y}

## Outcome Assessment

### Objectives Achieved
{What the flight accomplished}

### Mission Criteria Advanced
{Which success criteria this flight contributed to}

## What Went Well
{Specific things that worked effectively}

## What Could Be Improved

### Process
- {Recommendations for flight execution}

### Technical
- {Code quality, architecture, debt}

### Documentation
- {Gaps identified}

## Deviations and Lessons Learned

| Deviation | Reason | Standardize? |
|-----------|--------|--------------|
| {what changed} | {why} | {yes/no} |

## Key Learnings
{Insights for future flights}

## Recommendations
1. {Most impactful recommendation}
2. {Second recommendation}
3. {Third recommendation}

## Action Items
- [ ] {Immediate actions}
- [ ] {Near-term improvements}

---

Mission Debrief

Property	Value
Location	missions/{NN}-{mission}/mission-debrief.md
Created	After mission completes or aborts
Purpose	Post-mission retrospective and methodology improvements

Format:

# Mission Debrief: {Mission Title}

**Date**: {debrief date}
**Mission**: [{Mission Title}](mission.md)
**Status**: {completed | aborted}
**Duration**: {start} - {end}
**Flights Completed**: {X of Y}

## Outcome Assessment

### Success Criteria Results
| Criterion | Status | Notes |
|-----------|--------|-------|
| {criterion} | {met/not met} | {notes} |

### Overall Outcome
{Did we achieve what we set out to do?}

## Flight Summary
| Flight | Status | Key Outcome |
|--------|--------|-------------|
| {flight} | {landed/aborted} | {outcome} |

## What Went Well
{Effective patterns and successes}

## What Could Be Improved
{Process, planning, execution improvements}

## Lessons Learned
{Insights to carry forward}

## Methodology Feedback
{Improvements to Flight Control process itself}

## Action Items
- [ ] {Follow-up work}
- [ ] {Process improvements}

---

Maintenance Report

Property	Value
Location	maintenance/{YYYY-MM-DD}.md
Created	After a mission or ad-hoc, during routine maintenance
Purpose	Codebase health assessment and maintenance recommendation

Format:

# Maintenance Report: {YYYY-MM-DD}

**Date**: {report date}
**Triggered by**: [{Mission Title}](missions/{NN}-{slug}/mission.md) *(optional — omit if ad-hoc)*
**Assessment**: {Flight Ready | Maintenance Required}

## Categories Inspected
{Numbered list of categories that were checked}

## Executive Summary
{2-3 sentence overview of codebase health and key findings}

## Findings by Category

### Category {N}: {Name}

| # | Finding | Severity | New/Known | Recommendation |
|---|---------|----------|-----------|----------------|
| {n} | {title} | {severity} | {new/known} | {recommendation} |

**Details:**
{Per-finding evidence with file paths and line numbers}

## Severity Summary

| Severity | Count |
|----------|-------|
| Critical | {N} |
| Action Required | {N} |
| Advisory | {N} |
| Pass | {N} |

## Known Debt Carried Forward
{Debt items from debriefs that were acknowledged but not addressed, or "None — no prior debt context"}

## Recommendations
1. {Most impactful recommendation}
2. {Second recommendation}
3. {Third recommendation}

## Maintenance Mission
{Link to scaffolded mission if created, or "Not required — codebase is flight ready"}

---

State Tracking

States are tracked in the frontmatter or status field of each artifact:

Artifact	States
Mission	planning → active → completed (or aborted)
Flight	planning → ready → in-flight → landed → completed (or aborted)
Leg	planning → ready → in-flight → landed → completed (or aborted)

Conventions

• Immutability: Never modify legs once in-flight; create new ones instead
• Append-only logs: Flight logs are append-only during execution
• Flight briefings: Created before execution, not modified after
• Debriefs: Created after completion, may be updated with follow-up notes
• Mission as briefing: The mission.md document serves as both definition and briefing (no separate mission-briefing.md)

Git Workflow

Property	Value
Strategy	branch

Options:

• branch (default) — Single-checkout workflow. The orchestrator creates a feature branch and all agents work in the project root. One flight at a time per working copy.
• worktree — Worktree isolation. The orchestrator creates a git worktree under .worktrees/ for each flight. Agents work in the worktree path. Parallel flights are possible on a single repo clone.

When using the worktree strategy, add .worktrees/ to .gitignore.