82b9758be6
Some checks failed
test / contract-and-unit (push) Failing after 14s
BMAD-onboarding kit for the Damascus orchestrator:
- docs/adding-a-new-project.md — full onboarding guide covering layout,
required story section headers, common pitfalls (with the four classes
of bug that have cost real cycles here: Path.rglob doesn't follow
symlinks, architecture.md must be at planning-artifacts/architecture.md
exactly, missing section headers burn 3 retries each, etc.)
- bmad/_kit/ — read-only reference material (templates + sample)
- templates/{prd,architecture,epics,story}.md
- sample/hello-bmad/_bmad-output/ — one fully-formed worked example
(2-story FastAPI project, valid end-to-end)
- README.md — kit-level contract
- scripts/test-ingest.sh — pre-flight validation that catches the four
bug classes before any DB write. Verified against the live orchestrator
container: passes on the sample, fails (correctly) on a hand-broken tree
with both missing-section AND symlink bugs in one run.
- docker-compose.yml — replace /home/kaykayyali/_bmad bind (which
doesn't exist on this server) with ./bmad/_kit. Kit now ships with
the repo.
- .gitignore — re-include bmad/_kit/ so it travels with the repo while
keeping the existing 'bmad/ is ephemeral mount content' contract.
Verified end-to-end: 'damascus ingest --project hello-bmad' succeeded
on the live orchestrator, _find_bmad_story resolved both stories.
The 'architecture.md is ingested as a work item' quirk is documented in
docs/adding-a-new-project.md §'Common pitfalls' with a one-liner fix.
Refs: t_5aa80e4b (parallel dashboard work — committed separately)
BMAD Kit — Damascus Orchestrator
This directory is read-only reference material for new projects onboarding to the Damascus orchestrator. Copy from here, never add to it.
Contents
bmad/_kit/
├── README.md ← this file
├── templates/
│ ├── prd.md ← Product Requirements Document template
│ ├── architecture.md ← Architecture doc template (lives at planning-artifacts/architecture.md)
│ ├── epics.md ← Epics + story summary template
│ └── story.md ← Per-story brief template (required section headers)
└── sample/
└── hello-bmad/ ← one fully-formed worked example
└── _bmad-output/
├── planning-artifacts/
│ ├── architecture.md
│ └── stories/
│ ├── S1-hello-endpoint.md
│ └── S2-list-endpoints.md
└── meta/
└── prd.md
How to use
For a real onboarding, see docs/adding-a-new-project.md in the repo root. The short version:
# 1. Copy the sample as a starting point
cp -r bmad/_kit/sample/hello-bmad /root/my-project
# 2. Rename + edit
cd /root/my-project
mv _bmad-output/meta/prd.md{,.bak} # edit in place
# 3. Validate before going live
cd /root/damascus-orchestrator
./scripts/test-ingest.sh /root/my-project/_bmad-output my-project
# 4. Wire the bind mount + real ingest (see docs/adding-a-new-project.md)
Maintenance contract
Don't add to _kit/. The kit is the canonical reference — adding to it creates drift. If you find a new template pattern is needed, the right move is:
- Document the gap in
docs/adding-a-new-project.mdunder "Common pitfalls" or "Open decisions" - If the orchestrator needs a new capability, file an issue against
kaykayyali/damascus-orchestrator - If the gap is project-specific, copy + adapt from
_kit/templates/into your project's_bmad-output/, don't modify the kit
When the orchestrator changes
The kit must stay in sync with src/damascus/phases.py (which parses story sections) and src/damascus/cli.py (which does the ingest glob). When either changes:
- Update
templates/story.mdsection list to match - Update
scripts/test-ingest.shvalidation to match - Update
docs/adding-a-new-project.md"Common pitfalls" to match - Update the worked sample (
sample/hello-bmad/) to match
This is a manual chore. There's no automated lint linking the kit to the orchestrator code.