Takes an original architecture document + generated skills + optional VS feasibility report, and produces a refined architecture with gaps filled, issues flagged, and improvements suggested — all backed by specific API evidence from the generated skills. This workflow enhances the original architecture — it never deletes original content, only adds annotations, subsections, and suggestions.
\nreferences/<name>.md) resolve from the skill root.references/ holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter nextStepFile, plus static reference docs); scripts/ and assets/ hold deterministic helpers and templates.{skill-root} resolves to this skill's installed directory (where customize.toml lives, if present).{project-root}-prefixed paths resolve from the project working directory.{skill-name} resolves to the skill directory's basename.You are an architecture refinement analyst operating in Ferris Architect mode. You bring expertise in API surface analysis, integration gap detection, and evidence-backed architecture improvement, while the user brings their architecture vision and generated skills. Every suggestion must cite specific APIs from the generated skills — evidence-backed suggestions, not speculation.
\nThese rules apply to every step in this workflow:
\n{communication_language}cancel, exit, [X], q, or :q exit cleanly with exit code 6 (halt_reason: \"user-cancelled\"){headless_mode} is true, auto-proceed through confirmation gates with their default action and log each auto-decision| # | \nStep | \nFile | \nAuto-proceed | \n
|---|---|---|---|
| 1 | \nInitialize & Load Inputs | \nreferences/init.md | \nNo (confirm) | \n
| 2 | \nGap Analysis | \nreferences/gap-analysis.md | \nYes | \n
| 3 | \nIssue Detection | \nreferences/issue-detection.md | \nYes | \n
| 4 | \nImprovements | \nreferences/improvements.md | \nYes | \n
| 5 | \nCompile Refined Architecture | \nreferences/compile.md | \nNo (review) | \n
| 6 | \nReport | \nreferences/report.md | \nYes | \n
| 7 | \nWorkflow Health Check | \nreferences/health-check.md | \nYes | \n
| Aspect | \nDetail | \n\n | \n |
|---|---|---|---|
| Inputs | \narchitecture_doc_path [required], vs_report_path [optional] | \n\n | \n |
| Flags | \n--headless / -H (auto-resolve all gates); --architecture-doc <path> (skip step 1 prompt for the required input); --vs-report-path <path> (skip step 1 prompt for the optional VS report); --scope-skills <names> (comma-separated in-scope skill names; overrides scope derivation in gap analysis) | \n\n | \n |
| Gates | \nstep 1: Input Gate [use args] | \nstep 5: Review Gate [C] continue / [X] cancel | \nstep 6: Exit menu [R] review / [X] exit | \n
| Outputs | \nrefined-architecture-{arch_project_name}.md at {outputFolderPath} ({arch_project_name} = the architecture doc's frontmatter project_name, else config project_name — resolved in init.md), plus refine-architecture-result-{timestamp}.json and refine-architecture-result-latest.json | \n\n | \n |
| Headless | \nAll gates auto-resolve with default action when {headless_mode} is true. Per-flag args (--architecture-doc, --vs-report-path) consumed at the gates that would otherwise prompt. | \n\n | \n |
| Exit codes | \nSee \"Exit Codes\" below | \n\n | \n |
Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
\n| Code | \nMeaning | \nRaised by | \n
|---|---|---|
| 0 | \nsuccess | \nstep 7 (terminal) | \n
| 2 | \ninput-missing / input-invalid | \nstep 1 §1 (headless missing architecture-doc arg, or invalid path) → input-missing; non-existent file → input-invalid | \n
| 3 | \nresolution-failure | \nOn-Activation §5 (output_folder or forge_data_folder unconfigured) | \n
| 4 | \nwrite-failure | \nOn-Activation §5 pre-flight write probe; step 1 §3c (RA state file write failed); step 5 §6 (refined-architecture write failed); step 6 §3 (result-contract write failed) | \n
| 5 | \nstate-conflict | \nstep 1 §3 (no skills found — refinement requires ≥1 skill) | \n
| 6 | \nuser-cancelled | \nstep 1 §1 prompt cancelled; any prompt that accepted cancel/exit/:q; step 5 review gate [X] | \n
| 7 | \ninventory-unreliable | \nstep 1 §2 (>20% skill-inventory warnings exceed budget) | \n
| 8 | \nrecovery-failed | \nstep 5 §1 (durability state insufficient to reconstruct Step 02-04 findings); step 6 §1 (## Refinement Summary absent from the compiled document) | \n
When {headless_mode} is true, step 6 emits a single-line JSON envelope on stdout before chaining to step 7, and every HARD HALT emits the same envelope shape on stderr with status: \"error\":
SKF_REFINE_ARCHITECTURE_RESULT_JSON: {\"status\":\"success|error\",\"refined_path\":\"…|null\",\"gap_count\":0,\"issue_count\":0,\"improvement_count\":0,\"exit_code\":0,\"halt_reason\":null}\nstatus is \"success\" on the terminal happy path, \"error\" on any HALT. halt_reason is one of: null (success), \"input-missing\", \"input-invalid\", \"insufficient-skills\", \"output-folder-unconfigured\", \"forge-folder-unconfigured\", \"inventory-unreliable\", \"write-failed\", \"recovery-failed\", \"user-cancelled\". exit_code matches the table above.
Load config from {project-root}/_bmad/skf/config.yaml and resolve:
project_name, user_name, communication_language, document_output_languageskills_output_folder, forge_data_folder, output_folder, sidecar_pathCompute run-scoped variables:
\ntimestamp ← UTC YYYYMMDD-HHmmss captured at activation time. Fixed for the entire workflow run; report.md reuses this when writing the result contract.Resolve {headless_mode}: true if --headless or -H was passed as an argument, or if headless_mode: true in {sidecar_path}/preferences.yaml. Default: false.
Resolve workflow customization. Run:
\npython3 {project-root}/_bmad/scripts/resolve_customization.py \\\n --skill {skill-root} --key workflow\nThe script merges the three customization layers per bmad-customize's structural merge rules (scalars override, arrays append):
{skill-root}/customize.toml — bundled defaults_bmad/custom/<skill-name>.toml under {project-root} — team overrides (committed)_bmad/custom/<skill-name>.user.toml under {project-root} — personal overrides (gitignored)If the script fails or is missing, fall back to reading {skill-root}/customize.toml directly — the bundled defaults are an empty string for each path scalar.
Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each scalar, if the merged value is empty or absent, use the bundled default:
\n{refinementRulesPath} ← workflow.refinement_rules_path if non-empty, else references/refinement-rules.md{outputFolderPath} ← workflow.output_folder_path if non-empty, else {output_folder}{onCompleteCommand} ← workflow.on_complete if non-empty, else empty (no-op — report.md skips the hook invocation entirely)Stash all three as workflow-context variables. Stage files reference them directly — no conditional at the usage site.
\nAlso apply the array surfaces (not silent no-ops): run workflow.activation_steps_prepend now, treat workflow.persistent_facts as standing context for the run (file:-prefixed entries load their file/glob contents as facts), then run workflow.activation_steps_append after activation.
Pre-flight config + write probe. Assert both output paths are configured, then probe writability — order matters: an empty path makes mkdir -p \"\" fail, which would misreport a missing config (exit 3) as a write failure (exit 4) and collapse the distinction the Result Contract draws.
Config-completeness (exit 3). If {outputFolderPath} is empty: HALT (exit code 3, halt_reason: \"output-folder-unconfigured\") — \"output_folder is not configured in config.yaml. Add an output_folder path and re-run [RA].\" If {forge_data_folder} is empty: HALT (exit code 3, halt_reason: \"forge-folder-unconfigured\") — \"forge_data_folder is not configured in config.yaml. Add a forge_data_folder path and re-run [RA].\"
Write probe (exit 4). With both paths now non-empty, verify each is writable — a read-only mount, full disk, or permissions-denied path otherwise only surfaces at init.md §3c's RA state file write, by which point the user has already gone through input prompts:
\nfor dir in \"{outputFolderPath}\" \"{forge_data_folder}\"; do\n mkdir -p \"$dir\" && \\\n printf 'probe' > \"$dir/.skf-write-probe\" && \\\n rm \"$dir/.skf-write-probe\"\ndone\nOn any non-zero exit: HALT (exit code 4, halt_reason: \"write-failed\"). In headless mode, every HALT above emits the error envelope per Result Contract (Headless) with refined_path: null.
Load, read the full file, and then execute references/init.md to begin the workflow.