Claude-driven toolchain for fiftyfive-tech: turns a raw client brief into a scoped, architected, documented, ticketed and costed project — and turns day-to-day bug reports and QA findings into properly formatted Odoo tickets.
Everything here is Markdown skill files. There is no application to build or run. Claude reads a skill file and follows it; the "code" is the instructions.
skills/core — global rules (LAYER_0_GLOBAL), always loaded
skills/layers — intake skills loaded on demand (FASTPATH, QA_INTAKE)
skills/project-initiator — Project Initiator chain (START → ESTIMATOR)
context — TEAM_CONTEXT.md, PARKING_LOT.md, ESTIMATION_BENCHMARKS.md
docs/superpowers/specs — design spec per skill
docs/superpowers/plans — implementation plans
docs/ — SYSTEM_FLOW, DEMO_SCRIPT, PHASE_1_TEST_SUITE
tests/fixtures — synthetic engagement fixtures, one folder per skill
engagements/ — empty status-bucket scaffold (active/blocked/completed/archived)
CLAUDE.md — Claude Code instructions for this repo
Not in this repo, but referenced by it:
| Where it lives | Needed for | |
|---|---|---|
| Odoo MCP server | A separate repository — clone it alongside this one and connect it as an MCP server in your Claude client | Anything that writes to Odoo: BACKLOG_GENERATOR, ticket intake |
/ticket-context |
An installed Claude skill, not a file here | Role-aware handoff context for a ticket |
Everything else in this repo is plain Markdown — nothing to build, nothing to install. The Project Initiator chain (START → ESTIMATOR) runs with no MCP server at all, right up to the point BACKLOG_GENERATOR offers to push tickets.
| Purpose | Where you run it | |
|---|---|---|
| Project Initiator | Brief → scope → architecture → PRD → docs → backlog → estimate | An engagement folder |
| Ticket Intake | Bug reports, feature requests, QA batches → Odoo tickets | This repo |
Chain:
START → DISCOVERY → MVP_SYNTHESIZER → ARCH_PROPOSER → PRD_GENERATOR → DOC_GENERATOR → BACKLOG_GENERATOR → ESTIMATOR
Each skill is run manually. Every skill writes its output file and updates session_state.md
on completion, so you can stop after any step and resume in a later session.
Versions below are chain versions — the same number used in the section headings and in
CLAUDE.md's phase table. Each skill file also carries its own # VERSION: line, which tracks
edits to that file and will differ; the chain version is the one to quote.
| Skill | Chain version | Reads | Writes |
|---|---|---|---|
| START | V1.3 | engagement folders | project.md, session_state.md |
| DISCOVERY | V1.0 | input/* |
discovery.md |
| MVP_SYNTHESIZER | V1.1 | discovery.md |
mvp-scope.md |
| ARCH_PROPOSER | V1.3 | mvp-scope.md |
arch.md |
| PRD_GENERATOR | V1.7 | mvp-scope.md; optional discovery.md, arch.md |
prd.md |
| DOC_GENERATOR | V1.6.1 | discovery.md, mvp-scope.md, arch.md |
docs/*.md (5 files) |
| BACKLOG_GENERATOR | V1.4.1 | arch.md |
backlog.md + Odoo tickets |
| ESTIMATOR | V1.5.2 | arch.md, backlog.md; optional docs/proposal.md |
estimates.md |
~/fiftyfive-engagements/
ESTIMATION_BENCHMARKS.md ← working copy; master is context/ESTIMATION_BENCHMARKS.md
active/
<client-slug>/ ← one folder per engagement
input/ ← raw client docs (PDF, txt, md) — you put these here
project.md ← START
session_state.md ← every skill updates this
discovery.md ← DISCOVERY
mvp-scope.md ← MVP_SYNTHESIZER
arch.md ← ARCH_PROPOSER
prd.md ← PRD_GENERATOR
docs/ ← DOC_GENERATOR (5 files, fixed names)
backlog.md ← BACKLOG_GENERATOR
estimates.md ← ESTIMATOR
blocked/ completed/ archived/
Two rules that matter: run each skill from the engagement folder itself (not input/),
and let the folder name be the engagement name — most skills read it via basename.
skills/project-initiator/START.md
Entry point and router. Scans every engagement folder across all four status buckets, shows a registry with each one's stage and last session date, and tells you which skill to run next. Also creates new engagements and moves existing ones between buckets.
Parameters it asks for: client name, engagement name, project type (new engagement); or which registry entry to resume; or a status transition (active → blocked → completed → archived, and reactivation).
| Input | Output |
|---|---|
Existing engagement folders across active/ blocked/ completed/ archived/ |
<slug>/project.md, <slug>/session_state.md |
Sample prompts — run from ~/fiftyfive-engagements/:
run START
run START — new engagement for Acme Retail, an inventory platform, fixed-scope
run START — show me everything that's blocked and what each one is waiting on
run START — move acme-retail to completed
Does not: run any downstream skill for you.
skills/project-initiator/DISCOVERY.md
Reads raw client documents and extracts a structured picture. Assigns HIGH/MED/LOW confidence to each item, surfaces contradictions between documents, and asks only the gap questions that would block MVP_SYNTHESIZER.
Parameters it considers: every readable file in input/; confidence per extracted item;
conflicts (the same topic stated differently in two documents); which gaps are blocking versus
deferrable.
| Input | Output |
|---|---|
input/*.pdf, *.txt, *.md (at least one) |
discovery.md — Project Context, Users, Core Problem, Features Mentioned, Constraints, Open Questions, Confidence Notes, Source Docs |
Sample prompts — run from the engagement folder:
run DISCOVERY
run DISCOVERY — the transcript in input/ is the most current source; where the PDF
disagrees with it, treat the transcript as correct
run DISCOVERY — this is a regulated healthcare client, so treat any compliance or data
residency mention as a hard constraint rather than a nice-to-have
run DISCOVERY — I only have a two-page brief, so expect gaps; ask me everything you
need rather than inferring
Does not: choose architecture, define MVP scope, pick a stack, or create tickets.
skills/project-initiator/MVP_SYNTHESIZER.md
Decides what is in and out of the MVP. Runs a Readiness Gate on discovery.md first and
resolves BLOCKs inline rather than sending you back a step.
Parameters it asks for: the MVP framing — Time-boxed (what fits the deadline), Risk-first (what validates the riskiest assumption), or Value-first (what delivers most to the primary user). The framing drives every IN/OUT/DEFERRED call. Then: confirmation of each feature's disposition, 2–4 key user journeys, and success metrics.
| Input | Output |
|---|---|
discovery.md |
mvp-scope.md — Problem Restatement, Users, MVP Framing, Scope In/Out tables, Key User Journeys, Success Metrics, Constraints, Assumptions, Open Questions, Confidence Notes |
Sample prompts:
run MVP_SYNTHESIZER
run MVP_SYNTHESIZER — use time-boxed framing, the 30 September demo is immovable
run MVP_SYNTHESIZER — risk-first; the integration with their legacy ERP is the thing
most likely to sink this, so scope to prove that early
run MVP_SYNTHESIZER — the client insists all five features are must-have. Show me what
that does to the timeline before we agree to it
Does not: choose architecture or stack. Effort sizing is deferred to ARCH_PROPOSER, because sizing without architecture is noise.
skills/project-initiator/ARCH_PROPOSER.md
Turns scope into a technical plan. Treats stack choices already confirmed in mvp-scope.md as
locked, then walks the unconfirmed layers one at a time with options from fiftyfive-tech's
preferred stack.
Parameters it asks for: backend / database / infra / mobile choices where not already confirmed; team composition (roles and seniority); sprint length. It derives components per feature, integration points with risk ratings, build order, sprint mapping, and S/M/L/XL effort signals from component count plus integration risk.
[STRAWMAN] markers flag tentative decisions — these become blocking pre-condition tickets
in BACKLOG_GENERATOR, so they cannot be quietly forgotten.
| Input | Output |
|---|---|
mvp-scope.md |
arch.md — Client Summary, Tech Stack, Components, Data Model Hints, Integration Points, Build Order, Sprint Mapping, Effort Signals, Open Questions, STRAWMAN Summary |
Sample prompts:
run ARCH_PROPOSER
run ARCH_PROPOSER — the client is already on Azure with an enterprise agreement, so
default to Azure services unless there's a strong reason not to
run ARCH_PROPOSER — team is 2 backend, 1 frontend, 1 QA, all mid-level, two-week sprints
run ARCH_PROPOSER — we have not confirmed how their POS system exposes data. Mark
anything depending on it as STRAWMAN rather than assuming a REST API exists
Does not: create Odoo tickets.
skills/project-initiator/PRD_GENERATOR.md
Produces the requirements document the client proposal is written from. This is where user stories and scope-level acceptance criteria first appear in the chain.
Parameters it considers: every in-scope feature, and the journeys covering it. Stories are
derived one per covering journey — a feature named by two journeys with different actors
yields two stories with two roles, plus one story per capability no journey covers. Acceptance
criteria are derived from capabilities and journey outcomes, each labelled
(derived — confirm with client) until a human confirms them.
arch.md is optional: without it every section except §7 Dependencies is complete, and §7
is marked pending. So this runs either after ARCH_PROPOSER (complete) or straight after
MVP_SYNTHESIZER (§7 pending).
Scope cannot fork. Six of the nine sections are a derived view of mvp-scope.md. If you
try to change scope at the review gate, it redirects you upstream rather than letting the two
documents drift.
| Input | Output |
|---|---|
mvp-scope.md (required), discovery.md, arch.md (optional) |
prd.md at the folder root — Problem, Goals, Users, User Stories, Scope, Acceptance Criteria, Dependencies, Open Questions, Assumptions, Source Notes |
Sample prompts:
run PRD_GENERATOR
run PRD_GENERATOR — architecture isn't done yet, generate what you can and flag the rest
run PRD_GENERATOR — the client's QA lead will review the acceptance criteria, so make
each one something they can literally pass or fail in a test
Does not: write to docs/ (that is DOC_GENERATOR's), or change scope.
skills/project-initiator/DOC_GENERATOR.md
Generates client- and team-facing deliverables. Runs a Sync Check first that cross-validates the three input files; DRIFT items block the menu until resolved or deferred.
Parameters it asks for: which documents to generate (all, client, dev, or numbers);
DRIFT resolutions where the three inputs disagree; per-document approval before each save.
| # | Document | Filename | Audience |
|---|---|---|---|
| 1 | Project Proposal / SOW | proposal.md |
Client |
| 2 | Technical Architecture | architecture-doc.md |
Dev |
| 3 | Sprint Plan | sprint-plan.md |
Dev + PM |
| 4 | Developer Handoff | developer-handoff.md |
Dev |
| 5 | Scope Agreement | scope-agreement.md |
Client |
Filenames are constants — downstream skills resolve documents by these paths.
Client-facing documents (1 and 5) carry no framework or component names. The single exception is Scope Agreement §10 "What Changed Since MVP Scope", which must name technologies: the client signs that document, and a change they cannot identify is not a disclosure.
| Input | Output |
|---|---|
discovery.md, mvp-scope.md, arch.md |
docs/ with up to 5 fixed-name files, each with Mermaid diagrams |
Sample prompts:
run DOC_GENERATOR
run DOC_GENERATOR — client docs only, we're presenting tomorrow
run DOC_GENERATOR — generate 2 and 4, the devs need the architecture and handoff to
start estimating
run DOC_GENERATOR — the stack changed since mvp-scope was written; arch.md is correct,
resolve any drift that way
Does not: create Odoo tickets, or write prd.md.
skills/project-initiator/BACKLOG_GENERATOR.md
Turns architecture into a structured ticket hierarchy and creates it in Odoo.
Parameters it asks for: project name (defaults to folder name); stage list (defaults Backlog / To Do / In Progress / Bug / Done — custom stages trigger purpose-mapping questions); role → Odoo user ID mapping; approval before any write.
Writes backlog.md first, then offers a 3-option gate: create in Odoo now / run ESTIMATOR
first / skip and push later. Always runs a duplicate check before creating.
Ticket shape: one parent per Build Order item, subtasks per component. Backend tickets get API endpoint tables (or an Interfaces section for connectors and jobs); frontend tickets get screen and component lists. Both carry business rules, acceptance criteria, edge cases, and any Open Questions that block them. One Odoo tag per sprint.
| Input | Output |
|---|---|
arch.md |
backlog.md + Odoo project, stages, sprint tags, parent tickets and subtasks |
Sample prompts:
run BACKLOG_GENERATOR
run BACKLOG_GENERATOR — write backlog.md only, I want to review before anything
touches Odoo
run BACKLOG_GENERATOR — use our standard stages but add a "Blocked" stage after To Do
run BACKLOG_GENERATOR — backlog.md already exists from last week, push it to Odoo now
Requires: the Odoo MCP server connected. See Part 3.
skills/project-initiator/ESTIMATOR.md
Converts effort signals into hours, days, dates and optionally cost.
Parameters it asks for: estimate style (fixed hours or a low–high range); working hours per day (default 8); whether to include cost, and blended or per-role rates; delivery-phase percentages (QA / UAT / PM, defaults 20/5/10); project start date confirmation. Then a row-level adjustment loop before anything is written.
Estimation benchmarks. Built-in size values are authoritative and always available;
ESTIMATION_BENCHMARKS.md is an optional override shipping with the same numbers, so it
changes nothing until you deliberately edit it. Resolution order from the engagement folder:
./ → ../ → ../../. ESTIMATOR appends one row per run to its project log, with your
approval only.
Delivery phases are internal. QA/UAT/PM appear in the Summary, Section 2 and Section 3 — but never in Section 1, which is the extract that goes to a client. The Summary total therefore exceeds Section 1's total by design.
Scope-lock reconciliation. If docs/proposal.md exists, ESTIMATOR checks the estimate
covers exactly what was sold, and reports sold but not estimated and estimated but not sold.
Matching is structural, never by name — proposal capabilities are de-jargoned while Build Order
items are component names, so they never align textually.
| Input | Output |
|---|---|
arch.md, backlog.md, optional docs/proposal.md |
estimates.md — Summary, Section 1 (client), Section 2 (internal), Section 3 (assumptions) |
Sample prompts:
run ESTIMATOR
run ESTIMATOR — give me a range not fixed hours, the POS integration is too uncertain
for a single number
run ESTIMATOR — include cost at a blended 5000/day, and start the project 1 October
rather than the date in arch.md
run ESTIMATOR — no delivery phases this time, the client is handling their own QA
run ESTIMATOR — bump QA to 25%, this one has a heavy compliance test cycle
Runs identically in Claude Code and Claude Enterprise. No command needed — the input is routed automatically.
| Skill | File | Handles |
|---|---|---|
| LAYER_0_GLOBAL | skills/core/LAYER_0_GLOBAL.md |
Global rules, always loaded |
| LAYER_2_FASTPATH | skills/layers/LAYER_2_FASTPATH.md |
Bugs, features, improvements, requirements |
| QA_INTAKE | skills/layers/QA_INTAKE.md |
QA batches, numbered findings, TC-NNN references |
| BUG_REPORT_TEMPLATE | skills/core/BUG_REPORT_TEMPLATE.md |
Bug report formatting |
| /ticket-context | installed Claude skill — not a file in this repo | Role-aware handoff context for a ticket |
At session start Claude reads PARKING_LOT.md, LAYER_0_GLOBAL.md and TEAM_CONTEXT.md, then
asks who the session is — the answer populates the by: field on everything raised.
Sample prompts — run from this repo:
Login fails with a 500 when the email has a plus sign in it. Reproduces every time on staging.
QA batch from today's regression run:
1. TC-014 — checkout total ignores the discount code
2. TC-021 — order history pagination stops at page 3
3. TC-033 — profile photo upload silently fails over 2MB
Feature request from the client: they want to export the report as CSV as well as PDF.
what tickets are open for the payments module
/ticket-context 2541
Parking Lot. Anything too vague to ticket, or needing a product decision, goes to
context/PARKING_LOT.md with a TTL. Claude surfaces expiring items at session start.
park this — should subscriptions allow mid-cycle plan changes, or only at renewal?
Billing impact is unclear. Needs a PM decision.
what's in the parking lot right now
BACKLOG_GENERATOR and the intake skills write to Odoo through an MCP server that lives in a separate repository. Clone it alongside this one and register it as an MCP server in your Claude client — there is nothing to install from this repo.
Prerequisites
- Odoo MCP server running and connected
arch.mdcomplete with Build Order, Sprint Mapping and Effort Signals- Odoo user IDs for each role — configure in
context/TEAM_CONTEXT.md
Configure your instance in CLAUDE.md and context/TEAM_CONTEXT.md:
Instance: https://<your-org>.odoo.com
Project: <name> (ID: <project_id>)
Stages: Backlog(<id>) → To Do(<id>) → In Progress(<id>) → Bug(<id>) → Done(<id>)
Tags: frontend(<id>), backend(<id>), bug(<id>)
Team: Role → Odoo user ID
What appears after BACKLOG_GENERATOR runs: the project with your stage list, one tag per sprint, parent tickets per Build Order item with subtasks per component, each ticket carrying scope, endpoints or screens, business rules, acceptance criteria and edge cases. Nothing is created without explicit approval, and a duplicate check runs first.
The four status buckets the chain expects, committed empty — each holds only a .gitkeep.
engagements/
active/ ← in-flight
blocked/ ← waiting on a client pre-condition
completed/ ← delivered
archived/ ← closed out
Client work is not committed here. Live engagements live at ~/fiftyfive-engagements/ on
the consultant's machine, using the same four buckets. To see what each skill produces, use the
synthetic fixtures in tests/fixtures/ — they are maintained and scored on every skill change,
which a snapshot of real work is not.
Every skill has synthetic fixtures under tests/fixtures/<skill>/, each with an
expected_behaviors.md checklist, a TEST_SCRIPT.md giving the exact answers to type at each
prompt, and a test_report.md recording the score. All eight skills are covered.
Two reports still need writing: discovery/synthetic-01 and discovery/synthetic-02 have
fixtures and a script but no scored report yet.
tests/fixtures/start/TEST_SCRIPT.md carries a routing regression checklist — run all
three START fixtures after any change to stage detection or next-skill routing, since
detection is ordered and a change at one position can silently shift another.
Report format is not uniform: doc-generator, estimator, prd-generator and
backlog-generator use - [x] checkboxes; arch-proposer and start use a prose
PASS ✓ / Score: N/N style. Match whichever a fixture already uses, or convert a whole
skill's reports together — a count-based audit reads the checkbox style only.
run DOC_GENERATOR # from tests/fixtures/doc-generator/synthetic-01/
Generated artifacts (estimates.md, prd.md, docs/, session_state.md) are deleted after
scoring — they are not committed fixture inputs.
- Nothing is written without approval. Every skill shows a full draft and waits.
- Skills never modify their inputs. Each reads upstream artifacts and writes its own.
- One source of truth per fact.
mvp-scope.mdowns scope;prd.mdis a derived view. - Version headers. Every skill file starts with
# VERSION: x.y | Last updated: …. - Skill changes are re-uploaded to Claude Enterprise manually after review here.