From BRD to Code Without the Pain: An Artifact-Driven Development Playbook

This is the convention Onesist uses (AGENTS.md:131 + docs/README.md:13).

Why it matters:

• One source for all roles: SA, PM, and developers see the same folder. No "Excel on the SA's laptop" that isn't in the repo.
• AI can ready directly: Agent CLI (opencode, claude, codex) reads files in input/fsd/ without upload.
• Git-versioned: Every FSD -> ERD -> Spec change is in git log Reviewable like code.

The 7-Phase Pipeline (Run via Prompt, Not Buttons)

In onesist the workflow isn't button clicks it's prompts to the agent CLI in the emmbedded terminal. UI buttons are considered experomental; prompts are the way.

Each phase ends with review + finalization with the agent. Not final? Regenerate. Final? Move on. See full prompts in docs/en/08-prompt-library.md and best pratices in docs/en/09-best-pratices.md.

Key: Agent doesn't guess. It's validated with fsd-analyzer skill (validate_erd.py, validate_spec.py, compare_artifacts.py) + completeness checklist (lib/fsd-completeness.ts) whether User Journey, Edge Cases, Security are covered. Gaps like [GAP] FSD mentions refund but no refunds table are caught before coding starts.

Real Impact

After adopting this playbook (with or without Onesist):

• FSD -> ERD -> Spec drafting time: 3-4 days -> 1-1,5 days (AI generates draft, SA reviews & finalizes not writing from scratch).
• Synchronization: Zero manual copy-paste. Change FSD -> regenerate ERD -> gaps in Spec & Tasks auto-detected.
• Context preserved: 150-page FSD no longer makes AI forget because AI reads files, not chat history.
• Cost: $30/month workspace -> $0 (own CLI + API key, or local model).
• Traceability: RTM BR -> FR -> DS -> TC is clear which requirement lacks a test is visible.

Most valuable: SAs get time back to think does this flow handle race conditions? Are permissions correct? not to move data between tabs.

Three Biggest Lessons

1. Standardization > Prompt Engineering One solid fsd-analyzer skill beats 100 creative but inconsistent ad-hoc prompts. AI needs guardrails, not freedom.
2. Markdown Is the Lingua Franca Not Excel, not Confluence, not Jira. Git-versioned Markdown then rendered as ERD, Spec, Kanban, Gantt. One source, many views.
3. The Future SA Won't Be Replaced by AI But SAs who use AI will replace those who don't. Onesist is my attempt to ensure that transition reduces tool fatigue, not increases it.

Try It Yourself - 3 Steps

Option A - No install (today):

1. Create input/fsd/ and /output folders in your repo (template above).
2. Put FSD PDF in input/fsd/, run opencode run or claude -p with prompts from docs/en/08-prompt-library.md
3. See results - markdown, DBML, task cards right in the repo.

Option B - With Onesist (visual):

Desktop: bunx tauri dev (requires Rust).

Full docs: docs/README.md 10 bilingual guides + prompt library + best pratices.