cuioss/ref-workflow-architecture

Plan-Marshall Architecture

Central architecture reference for the plan-marshall bundle. Provides documentation of the 6-phase execution model, thin agent pattern, data layer, and workflow conventions.

Load specific standards on-demand based on what aspect you need to understand.

Standards Documents

| Document | Focus | Key Content | |----------|-------|-------------| | phases.md | 6-phase model | Phase flow, transitions, outputs, iteration limits | | agents.md | Thin agent pattern | Agent structure, Skill: vs Task: invocation | | call-graph.md | Holistic dispatch call graph | Mermaid diagrams: per-phase detail, 6-group phase-scoped registry overlay, dispatch-vs-script verdict table — every dispatch path starting from plan-marshall | | dispatch-walkthrough.md | Worked dispatch traces | Three end-to-end examples: phase-2-refine entry, finalize automated-review with verification-feedback (producer=pr-comment), architecture-refresh Tier-1 fan-out | | dispatch-logging.md | Standardized dispatch log line | Post-resolve [DISPATCH] emission contract — five literal fields (target, level, role, workflow, plan_id), placement after effort resolve-target and before Task: plan-marshall:{target}, canonical manage-logging work invocation, positive example + anti-pattern | | data-layer.md | manage-* skills | Inventory, dependency graph, data flow | | manage-contract.md | manage-* contract | Enforcement, error codes, shared formats | | skill-loading.md | Two-tier loading | System vs domain skills, domain flow through phases | | artifacts.md | Plan file formats | status.json, TASK-*.json, references.json, logs | | execute-task-skills.md | Execute-task skills | Profile routing, shared workflow, extensibility | | change-types.md | Change type vocabulary | analysis, feature, enhancement, bug_fix, tech_debt, verification | | glossary.md | Terminology definitions | plan_id, phase, profile, module, domain, deliverable, task, finding, TOON | | phase-lifecycle.md | Phase lifecycle patterns | Entry protocol, completion protocol, enforcement template, error convention | | skill-inventory.md | Complete skill inventory | 49 skills: registration status, categories, naming convention | | terminal-title-architecture.md | Terminal-title writer/reader split | manage-status writer (_render_title_body/_publish_title_body → title-body.txt), platform-runtime reader (session_render_title: session → active-plan → title-body → {icon} {body}), title-body lifecycle incl. archive + Completed body, OSC-hook vs statusLine channels, claude-vs-opencode abstraction, canonical 3-icon palette (➤ / ? / ✓) |

The data-layer and manage-contract standards above define the cwd-agnostic Bucket A contract for manage-* scripts. See workflow-integration-git/standards/worktree-handling.md for the worktree-specific application of this rule (the complementary Bucket B --plan-id contract for working-tree-bound scripts).

Core Principles

1. Domain-agnostic workflow — Workflow skills contain no domain-specific logic. Domain knowledge comes from marshal.json at runtime.
2. Thin agent pattern — A single parameterized agent with different phase parameters, delegating to skills for actual work.
3. Single source of truth — Plan files are the source of truth. Skills read/write via manage-* scripts only.
4. Script-based file access — ALL .plan/ file access goes through execute-script.py. Never use Read/Write/Edit on .plan/ files directly.

Related

| Skill | Purpose | |-------|---------| | plan-marshall:plan-marshall | Unified user-facing entry point for plan lifecycle | | plan-marshall:extension-api | Extension points for domain customization | | plan-marshall:execute-task | Unified execute-task skill (implementation, module_testing, verification profiles) | | plan-marshall:shared-workflow-helpers | Shared Python infrastructure for workflow scripts |

Shared Workflow Infrastructure

All workflow scripts share triage_helpers from shared-workflow-helpers (marketplace/bundles/plan-marshall/skills/shared-workflow-helpers/scripts/triage_helpers.py). See plan-marshall:shared-workflow-helpers SKILL.md for the module overview.

Workflow Skill Conventions

Script-bearing workflow skills follow this canonical section order (sections marked optional may be omitted when not applicable):

---
name: workflow-<name>
description: <one-line description>
user-invocable: true|false
---

# <Title> Skill
## Enforcement
## Parameters          (optional)
## Prerequisites       (optional)
## Workflow(s)
## Scripts
## Error Handling
## Standards (Load On-Demand)
## Related

Config Loading Convention

Script-bearing workflow skills load JSON config from standards/ using load_skill_config(__file__, 'config-name.json') from triage_helpers.

Priority Vocabulary

All workflow scripts use the shared PRIORITY_LEVELS tuple from triage_helpers: low, medium, high, critical. Do not use none or other values.

Error Handling Patterns

All workflow skills use a consistent | Failure | Action | table. Common patterns:

| Pattern | Action | |---------|--------| | Script returns error | Report error to caller with details. Do not proceed. | | Triage/classification failure | Log warning, skip item, continue remaining. | | Push failure | Report error. Never force-push as fallback. | | Build verification failure | Report failing tests/compilation. Do not commit broken state. | | Max fix attempts reached | Report remaining issues. Do not loop further. |