ref-workflow-architecture
Centralized architecture documentation for the plan-marshall bundle with visual diagrams
Resources
1Install
npx skillscat add cuioss/plan-marshall/ref-workflow-architecture Install via the SkillsCat registry.
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 | ASCII box 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 | Seam [DISPATCH] emission contract — five literal fields (target, level, role, workflow, plan_id), emitted by effort resolve-target itself (per firing) when passed the dispatch context (--workflow/--plan-id/--caller), plus the paired decision-log record and the corroboration limit, positive example + anti-pattern |
| citations-only-return.md | Read-only dispatch return shape | One TOON summary, no free prose; sink-persistence obligation; ## Applies to roster (the conformance detector's population); untrusted-ingestion boundary explicitly out of scope |
| 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 dispatch, 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 |
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
- Domain-agnostic workflow — Workflow skills contain no domain-specific logic. Domain knowledge comes from marshal.json at runtime.
- Thin agent pattern — A single parameterized agent with different
phaseparameters, delegating to skills for actual work. - Single source of truth — Plan files are the source of truth. Skills read/write via manage-* scripts only.
- Script-based file access — ALL
.plan/file access goes throughexecute-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)
## RelatedConfig 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. |
Categories
Install
npx skillscat add cuioss/plan-marshall/ref-workflow-architecture Install via the SkillsCat registry.