By artifact type+ID

1. Global Overview

Scopes

Core Principles

• .workflow/ is added to .gitignore and excluded from version control (project.md as optional exception)
• All artifact paths are relative to the .workflow/ root directory
• Each directory/file has a single responsibility with no overlapping storage
• All command outputs are registered through state.json.artifacts[], enabling cross-phase tracking

2. Directory Tree

.workflow/
├── state.json                    # Project state machine + Artifact Registry
├── config.json                   # User workflow configuration
├── project.md                    # Project definition (Core Value, Requirements, Key Decisions)
├── roadmap.md                    # Milestone/phase roadmap
├── wiki-index.json               # Wiki unified index (auto-generated by WikiIndexer)
│
├── specs/                        # Specification files (6 types, project-level)
│   ├── coding-conventions.md     # Coding conventions (core)
│   ├── architecture-constraints.md # Architecture constraints (core)
│   ├── knowhow.md                # Knowledge index (core)
│   ├── quality-rules.md          # Quality rules (optional)
│   ├── test-conventions.md       # Test conventions (optional)
│   ├── debug-notes.md            # Debug notes (optional)
│   ├── review-standards.md       # Review standards (optional)
│   └── learnings.md              # Learning records (optional)
│
├── knowhow/                      # Knowledge documents (9 prefixes + learn special prefixes)
│   ├── .maestro-learn/           # maestro-learn session state
│   ├── KNW-*.md                  # session
│   ├── TIP-*.md                  # tip
│   ├── TPL-*.md                  # template
│   ├── RCP-*.md                  # recipe
│   ├── REF-*.md                  # reference
│   ├── DCS-*.md                  # decision
│   ├── AST-*.md                  # asset
│   ├── BLP-*.md                  # blueprint
│   ├── DOC-*.md                  # document
│   ├── KNW-follow-*.md           # maestro-learn follow
│   ├── KNW-decompose-*.md        # maestro-learn decompose
│   ├── KNW-retro-*.md/json       # retrospective step
│   ├── KNW-opinion-*.md          # maestro-learn consult
│   ├── KNW-investigate-*/        # maestro-learn investigate
│   ├── KNW-digest-*.md           # wiki-digest
│   └── wiki-connections-*.md     # wiki-connect
│
├── scratch/                      # Execution artifacts ({YYYYMMDD}-{type}[-P{N}]-{slug})
│   ├── *-analyze-*/              # Analysis: discussion.md, analysis.md, conclusions.json, context.md, context-package.json
│   ├── *-plan-*/                 # Planning: plan.json, .task/TASK-*.json
│   │   └── .summaries/           # Execution: TASK-{NNN}-summary.md
│   ├── *-verify-*/               # Verification: verification.json
│   ├── *-review-*/               # Review: review.json
│   ├── *-debug-*/                # Debug: understanding.md, evidence.ndjson
│   ├── *-test-*/                 # Test: uat.md, test-results.json, coverage-report.json
│   ├── *-auto-test-*/            # Auto-test: report.json
│   ├── *-brainstorm-*/           # Brainstorm: guidance-specification.md, {role}/, context-package.json
│   ├── *-collab-*/               # Collab: collab-report.md, context.md, context-package.json, per-tool/
│   ├── *-import-*/               # Document import: source.{ext}, context-package.json
│   └── *-ui-design-*/            # UI design: MASTER.md, design-tokens.json
│
├── issues/                       # Issue tracking
│   ├── issues.jsonl              # Active issues
│   ├── issue-history.jsonl       # Archived issues
│   └── discoveries/              # Discovery sessions
│
├── milestones/                   # Milestone archives
│   └── {M}/
│       ├── artifacts/            # Archived artifacts
│       ├── audit-report.md
│       ├── summary.md
│       └── roadmap-snapshot.md
│
├── codebase/                     # Codebase documentation (generated by mapper agent)
│   ├── doc-index.json
│   ├── tech-stack.md
│   ├── architecture.md
│   ├── features.md
│   └── concerns.md
│
├── blueprint/                    # Specification blueprint (blueprint step)
│   ├── blueprint-config.json
│   ├── product-brief.md
│   ├── glossary.json
│   ├── requirements/REQ-*.md, NFR-*.md
│   ├── architecture/ADR-*.md
│   ├── epics/EPIC-*.md
│   ├── readiness-report.md
│   └── blueprint-summary.md
│
├── collab/                       # Human team collaboration
│   ├── specs/                    # Team-level specs
│   └── specs/{uid}/              # Personal-level specs
│
├── .maestro/                     # Agent session state (internal)
│   ├── maestro-*/status.json
│   ├── ralph-*/status.json
│   └── coord-*/walker-state.json
│
├── .team/{session-id}/.msg/      # Agent team message bus
│   └── messages.jsonl
│
├── templates/design-drafts/      # Workflow template design drafts
├── reference_style/              # UI design system reference
├── impeccable/                   # Impeccable UI design context
│   ├── PRODUCT.md
│   ├── DESIGN.md
│   ├── design.json
│   ├── critique/
│   └── live/config.json, sessions/
│
├── worktrees.json                # Worktree registry
├── worktree-scope.json           # Worktree scope marker
├── harvest-log.jsonl             # Harvest log
└── harvest-report-{date}.md      # Harvest report

3. Core File Details

state.json Schema

{
  "version": "3.0",
  "status": "idle|active",
  "current_milestone": "M1",
  "current_phase": 1,
  "milestones": [{ "id": "M1", "status": "active|completed|forked", "phases": [1, 2] }],
  "milestone_history": [{ "milestone_id": "M1", "completed_at": "ISO-8601" }],
  "artifacts": [{ "id": "ANL-001", "type": "analyze", "path": "scratch/...", "status": "completed" }],
  "artifact_archive": [{ "id": "ANL-000", "type": "analyze", "milestone": "M0", "graduated_at": "ISO-8601", "knowhow_ref": "graduated-analyze-ANL-000", "summary": "..." }],
  "accumulated_context": {
    "key_decisions": [{ "decision": "...", "rationale": "...", "source": "analyze:ANL-001", "locked_at": "ISO-8601" }],
    "deferred": [{ "title": "...", "reason": "...", "status": "open|resolved|cancelled|superseded", "source": "..." }],
    "blockers": [{ "title": "...", "severity": "...", "status": "open|investigating|resolved", "source": "..." }]
  },
  "last_pruned": "ISO-8601"
}

artifacts[] Schema

{
  "id": "ANL-001",
  "type": "analyze",
  "milestone": "M1",
  "phase": 1,
  "scope": "phase|milestone|adhoc|standalone",
  "path": "scratch/20260513-analyze-P1-auth",
  "status": "created|completed|failed",
  "depends_on": null,
  "harvested": false,
  "context_package": "scratch/20260513-analyze-P1-auth/context-package.json",
  "created_at": "ISO-8601",
  "completed_at": "ISO-8601"
}

artifact_archive[] Schema

harvest --prune migrates graduated artifacts from artifacts[] to this array. Files remain on disk; only the state.json reference moves.

{
  "id": "ANL-001",
  "type": "analyze",
  "milestone": "M1",
  "path": "scratch/20260315-analyze-P2-security",
  "graduated_at": "ISO-8601",
  "knowhow_ref": "graduated-analyze-ANL-001",
  "summary": "Security audit P2 — 8 fragments → 3 wiki, 2 spec, 3 issue"
}

accumulated_context Management

accumulated_context grows over the project lifecycle. harvest --prune cleans it with these rules:

Artifact Lifecycle

created → completed → harvested → archived
                     ↘ failed

4. Knowledge System

specs/ — Specification Files

Uses <spec-entry> closed-tag format, automatically indexed by WikiIndexer.

Spec Scopes:

<spec-entry category="coding" keywords="exports,naming" date="2026-05-13" source="manual">
  Specification content...
</spec-entry>

knowhow/ — Knowledge Document Prefixes

Filename format: {PREFIX}-{YYYYMMDD}-{HHMM}.md

Learn special prefixes: KNW-follow-, KNW-decompose-, KNW-retro-, KNW-opinion-, KNW-investigate-, KNW-digest-

5. Issue Tracking

issues/issues.jsonl — one JSON object per line:

{
  "id": "ISS-XXXXXXXX-NNN",
  "title": "Issue description",
  "severity": "blocker|critical|major|minor|cosmetic",
  "status": "open|registered|planned|in_progress|resolved|closed",
  "source": "discover|review|verify|retrospective|harvest",
  "phase": 1,
  "tags": [], "related_files": [], "task_refs": [],
  "analysis": { "root_cause": "...", "fix_direction": "...", "confidence": "high|medium|low" },
  "history": [{ "action": "created|analyzed|planned|executed|closed", "at": "ISO-8601" }]
}

• issues/issue-history.jsonl — archived closed issues
• issues/discoveries/ — issue-discover step session artifacts

6. Milestone Archives

Created by /maestro-session-seal when a milestone is completed:

1. Verifies all runs are complete → audit-report.md
2. Scratch artifacts moved into milestones/{M}/artifacts/
3. state.json.artifacts[] entries moved to milestone_history[]
4. Final knowhow extracted, workflow advances to next milestone

7. Global Paths (~/.maestro/)

~/.maestro/
├── cli-tools.json              # CLI tool config (delegate routing)
├── workflows/                  # Workflow definitions (maestro.md, plan.md, execute.md, 40+ files)
├── templates/                  # Template system (state.json, plan.json, task.json, workflows/, etc.)
├── overlays/                   # Command extensions (*.json, docs/, _shipped/)
└── specs/                      # Global specifications (*.md)

8. Naming Convention Quick Reference

Scratch Directories

Format: {YYYYMMDD}-{type}[-P{N}|-M{N}]-{slug}

Artifact Types and Commands

Session ID Formats

9. Context Package System

Motivation

Downstream commands (roadmap / analyze / plan / blueprint) consuming upstream outputs suffer from three issues:

1. Format coupling — each consumer hardcodes upstream file structure (e.g., roadmap knows guidance-specification.md §10 is features)
2. Closed input — only --from-brainstorm is supported; no way to feed arbitrary user documents (PRDs, RFCs, meeting notes)
3. Value leakage — brainstorm role analyses (Decision Digests) are underutilized by roadmap/plan

Context Package is the standard data contract across commands — upstream outputs in a unified schema, downstream consumes via a unified interface.

Placement

Each context-producing session generates context-package.json within its directory. The artifact entry in state.json points to it via the context_package field.

.workflow/scratch/20260521-brainstorm-cache/
├── guidance-specification.md         # Original output (preserved)
├── system-architect/analysis.md      # Original output (preserved)
├── context.md                        # Human-readable summary (preserved)
└── context-package.json              # Standardized machine contract (new)

Not placed at root — avoids multi-session overwrite conflicts, preserves provenance.

Context Package Schema

{
  "$schema": "context-package/1.0",

  // ── Provenance ──
  "source": {
    "type": "brainstorm|analyze|collab|import",
    "artifact_id": "BRN-001",
    "session_path": "scratch/20260521-brainstorm-cache/",
    "generated_at": "2026-05-21T12:00:00Z"
  },

  // ── Requirements ── Primary consumer: roadmap, spec-gen
  "requirements": [
    {
      "id": "F-001",
      "title": "User authentication system",
      "description": "Support OAuth2 + local password login",
      "priority": "must|should|may",
      "acceptance": "Users can log in via Google/GitHub OAuth",
      "ref": "guidance-specification.md#§10"
    }
  ],

  // ── Constraints ── Primary consumer: plan, execute
  "constraints": [
    {
      "id": "C-001",
      "area": "authentication",
      "constraint": "MUST use stateless JWT tokens",
      "rationale": "Cannot share sessions across microservices",
      "status": "locked|open|deferred",
      "ref": "system-architect/analysis.md#§2-Decisions"
    }
  ],

  // ── Domain Knowledge ──
  "domain": {
    "problem_statement": "...",
    "terminology": [
      { "term": "Tenant", "definition": "Multi-tenant isolation unit", "ref": "guidance-specification.md#§5" }
    ],
    "audience": "Enterprise users",
    "industry": "SaaS"
  },

  // ── Exclusions ──
  "non_goals": [
    { "title": "Mobile adaptation", "rationale": "V2 scope", "ref": "guidance-specification.md#§6" }
  ],

  // ── Role Insights ── Direct use by plan (optional, brainstorm only)
  "insights": [
    {
      "role": "system-architect",
      "area": "data-model",
      "summary": "Recommend PostgreSQL JSONB for tenant config storage",
      "ref": "system-architect/analysis.md#§3-Data-Model"
    }
  ],

  // ── Open Questions ── Primary consumer: analyze
  "open_questions": [
    {
      "area": "caching",
      "question": "Redis vs Memcached for session cache?",
      "options": ["Redis (feature-rich)", "Memcached (simpler)"],
      "ref": "guidance-specification.md#§8"
    }
  ],

  // ── Source File References ── For deep reads on demand
  "references": [
    { "type": "guidance", "path": "guidance-specification.md" },
    { "type": "role-analysis", "path": "system-architect/analysis.md" },
    { "type": "role-analysis", "path": "ux-expert/analysis.md" }
  ]
}

Field Reference:

Per-item ref format: {file}#{section-anchor}, paths relative to session directory. Used for:

• Locating provenance during multi-source merge conflicts
• Deep-reading full context behind a specific constraint
• Annotating original source when harvest extracts knowledge fragments

Source Adapter Mappings

Unified Input: --from Flag

Replaces --from-brainstorm (retained as alias), supporting multiple input sources:

# --from argument patterns accepted by the roadmap / plan / analyze steps (dispatched within a Session chain):

# By artifact type+ID
roadmap --from brainstorm:BRN-001
plan --from analyze:ANL-002

# By session path
plan --from .workflow/scratch/20260521-brainstorm-cache/

# Import external documents (auto-creates import session)
roadmap --from @requirements.md
analyze --from @competitor-analysis.pdf

# Multi-source merge
plan --from brainstorm:BRN-001 --from @tech-constraints.md

# Backward compatible alias
roadmap --from-brainstorm SESSION-ID   # equivalent to --from brainstorm:{resolve(SESSION-ID)}

Resolution Priority:

Multi-source Merge Strategy:

External Document Import Flow

roadmap --from @prd.md
    │
    ├── 1. Create import session: .workflow/scratch/{date}-import-prd/
    ├── 2. Copy original document → source.{ext}
    ├── 3. Delegate extraction (analysis mode) → context-package.json
    ├── 4. Register artifact: { type: "import", context_package: "..." }
    └── 5. Return package for consumption (reuse later: --from import:IMP-001)

Extraction happens once — subsequent commands read the existing context-package.json without re-extraction.

Relationship with accumulated_context

Linkage: When analyze completes, it both generates a context-package (for future --from queries) and incrementally syncs locked decisions into accumulated_context.key_decisions[] to ensure global constraint propagation.

Command Consumption Changes

Anti-Patterns