references/orchestrator.md · 48000
max 1 sentence
- Remove redundant fields that duplicate markdown content
- The JSON is for MATCHING, not for reading — brevity is key
-
Write assessment (
0-assessment.md)- Reference:
output-formats.mdfor assessment template - Reference:
skeletons/skeleton-assessment.md— read this skeleton, copy VERBATIM, fill in[FILL]placeholders - ⚠️ ALL 7 sections are MANDATORY: Report Files, Executive Summary, Action Summary (with Quick Wins), Analysis Context & Assumptions (with Needs Verification + Finding Overrides), References Consulted, Report Metadata, Classification Reference
- Do NOT add extra sections like "Severity Distribution", "Architecture Risk Areas", "Methodology Notes", or "Deliverables" — these are NOT in the template
⛔ PRE-WRITE GATE — Verify before calling
create_filefor0-assessment.md:- Exactly 7 sections: Report Files, Executive Summary, Action Summary, Analysis Context & Assumptions (with
&), References Consulted, Report Metadata, Classification Reference ---horizontal rules between EVERY pair of##sections (minimum 6)### Quick Wins,### Needs Verification,### Finding Overridesall present- References: TWO subsections (
### Security Standards+### Component Documentation) with 3-column tables and full URLs - ALL metadata values wrapped in backticks; ALL fields present (Model, Analysis Started, Analysis Completed, Duration)
- Element/finding/threat counts match actual counts from other files
⛔ Fail-fast gate: Immediately after writing, run the Inline Quick-Checks for
0-assessment.mdfromverification-checklist.md. Fix before proceeding. - Reference:
-
Final verification — iterative correction loop
This step runs verification and fixes in a loop until all checks pass. Do NOT finalize with any failures remaining.
Pass 1 — Comprehensive verification:
- Delegate to a verification sub-agent with the content of
verification-checklist.md+ the output folder path - Sub-agent runs ALL Phase 0–5 checks and reports PASS/FAIL with evidence
- If ANY check fails:
- Fix the failed file(s) using the available file-edit tool
- Re-run ONLY the failed checks against the fixed file(s)
- Repeat until the failed checks pass
Pass 2 — Regression check (if Pass 1 had fixes):
- Re-run Phase 3 (cross-file consistency) to ensure fixes didn’t break other files
- If new failures appear, fix and re-verify
Exit condition: ALL phases report 0 failures. Only then mark the analysis as complete.
Sub-agent context management:
- Include the relevant phase content from
verification-checklist.mdin the sub-agent prompt - Include the output folder path so the sub-agent can read files
- Sub-agent output MUST include: phase name, total checks, passed, failed, and for each failure: check ID, file, evidence, exact fix instruction. Do not return "looks good" without counts.
- Delegate to a verification sub-agent with the content of
Tool Usage
Progress Tracking (todo)
- Create todos at start for each major phase
- Mark in-progress before starting each phase
- Mark completed immediately after finishing each phase
Sub-task Delegation (agent)
Delegate NARROW, READ-ONLY tasks to sub-agents (see Sub-Agent Governance above). Allowed delegations:
- Context gathering: "Search for auth patterns in these directories and return a summary"
- Code analysis: "Read these files and identify security-relevant APIs, credentials, and trust boundaries"
- Verification: Hand the verification sub-agent the content of
verification-checklist.mdand the output folder path. It reads the files and returns PASS/FAIL results. The PARENT fixes any failures. - JSON generation (exception): For large repos, delegate
threat-inventory.jsonwriting with exact file path and pre-computed data
NEVER delegate: "Write 0.1-architecture.md", "Generate the STRIDE analysis", "Perform the threat model analysis", or any prompt that would cause the sub-agent to independently produce report files.
Verification Checklist (Final Step)
The full verification checklist is in verification-checklist.md. It contains 9 phases:
Authority hierarchy:
orchestrator.mddefines the AUTHORING rules (what to do when writing reports).verification-checklist.mddefines the CHECKING rules (what to verify after writing). Some rules appear in both files for visibility — if they ever conflict,orchestrator.mdrules take precedence for authoring decisions, andverification-checklist.mdtakes precedence for pass/fail criteria. For the complete list of all structural, diagram, and consistency checks, always consultverification-checklist.md— it is the single source of truth for quality gates.
- Phase 0 — Common Deviation Scan: Known deviation patterns with WRONG→CORRECT examples
- Phase 1 — Per-File Structural Checks: Section order, required content, formatting
- Phase 2 — Diagram Rendering Checks: Mermaid init blocks, classDef, styles, syntax
- Phase 3 — Cross-File Consistency Checks: Component coverage, DF mapping, threat-to-finding traceability
- Phase 4 — Evidence Quality Checks: Evidence concreteness, verify-before-flagging compliance
- Phase 5 — JSON Schema Validation: Schema fields, array completeness, metrics consistency
- Phase 6 — Deterministic Identity: Component ID stability, boundary naming, flow ID consistency
- Phase 7 — Evidence-Based Prerequisites: Prerequisite deployment evidence, coverage completeness
- Phase 8 — Comparison HTML (incremental only): HTML structure, change annotations, CSS
Inline Quick-Checks: verification-checklist.md also contains Inline Quick-Checks that MUST be run immediately after writing each file (before Step 10). These catch errors while content is still in active context.
Two-pass usage:
- Before writing (Workflow pre-work): Scan Phase 1 and Phase 2 to internalize structural and diagram quality gates. This prevents rework.
- After writing (Step 10): Run ALL Phase 0–4 checks comprehensively against the completed output. Phase 0 is the most critical — it catches the deviations that persist across runs. Fix any failures before finalizing.
Delegation: Hand the verification sub-agent the content of verification-checklist.md and the output folder. It will run all checks and produce a PASS/FAIL summary. Fix any failures before finalizing.
Starting the Analysis
If no folder path is provided, analyze the entire repository from its root.