Powerhouse Software Team
Overview
Run a complete AI software development team: PM plans, Dev builds, QA reviews — all gated by spec documents and a strict layer build order.
Core principle: No code without a spec. No Layer N without Layer N-1 complete.
Target: Claude Code, OpenCode, Kimi Code. Works in both single-project repos and monorepos.
The Three Anchor Documents
Write these before any code. They are contracts, not documentation:
| Document |
Purpose |
| TECH_SPEC.md |
Data contract — schemas, collections, service signatures |
| SCREEN_SPEC.md |
UX contract — every screen in ASCII or wireframe |
| BUILD_STATUS.md |
Progress tracker — checkboxes per layer, updated after every merge |
Hard rule: No spec = STOP. Write the spec first, then plan the ticket.
Layered Build Order
Enforce N-1 before N. Typical full-stack app stack:
| Layer |
Name |
What goes here |
| 1 |
Types & Constants |
Interfaces, enums, color tokens, config |
| 2 |
Services |
Data access — CRUD, auth, storage |
| 3 |
Context & Hooks |
State management, business logic |
| 4 |
Base Components |
Reusable UI primitives |
| 5 |
Screens / Pages |
Full route implementations |
| 6 |
Backend Functions |
Cloud functions, webhooks, scheduled jobs |
| 7 |
Integration & Polish |
Wire together, performance, real data |
Adapt layer names and count to your stack. The gate rule is universal.
Agent Pipeline (every feature)
PM Tech Lead → [Research?] → Dev Engineer → QA Engineer → Human Approve → Merge
| Agent |
Responsibility |
| PM Tech Lead |
Plans ticket, enforces N-1 gate, defines scope + out-of-scope |
| Research Engineer |
Investigates new APIs/integrations — skip for standard CRUD |
| Dev Engineer |
Implements ticket exactly — no more, no less |
| QA Engineer |
Validates against TECH_SPEC + SCREEN_SPEC schemas |
Create agent files at .claude/agents/ — one markdown file per agent with role, trigger, and output format.
Step 5b — Browser verification (web projects only): After code review, the QA Engineer uses /browse to verify the built UI in a real browser:
- Console — no JS errors after page load
- Critical UI elements present
- Main user flow works end-to-end
- Layout holds at mobile + desktop
Skip this step for mobile apps, CLIs, and backend-only features.
Monorepo Support
If your project is a monorepo with multiple sub-projects, scope all commands to the active sub-project.
Sub-project detection (in order):
- User passes
--project <name> explicitly → use it
- CWD is inside a sub-project directory → infer from path
- CWD is repo root → show root-level BUILD_STATUS.md
- Ambiguous → ask once: "Which sub-project?"
Implementation:
def detect_project(args: list, cwd: str, root_path: str) -> str:
if "--project" in args:
idx = args.index("--project")
return args[idx + 1]
rel = os.path.relpath(cwd, root_path)
parts = rel.split(os.sep)
if parts[0] in ("mcps", "skills") and len(parts) >= 2:
return parts[1]
return "root"
Unified Command: /pst
| Sub-command |
Action |
status [--project <name>] |
Read BUILD_STATUS, current layer + next unchecked task |
plan [feature] |
Invoke PM Tech Lead → structured ticket |
build |
Invoke Dev Engineer → implement current ticket |
review |
Invoke QA Engineer → validate changes |
branch [name] |
Create feature/{subproject}/L{N}-{name} |
pr |
Type-check → rebase → push → create PR |
next |
Find first unchecked item across all sub-projects |
Auto-Routing
| User says |
Action |
| "build X", "create X", "add X" |
PM Tech Lead ticket first |
| "review", "check", "QA" |
QA Engineer |
| "done", "merge", "PR" |
Finish-feature flow |
| "status", "what's next" |
Read BUILD_STATUS |
| "research X", "how does X work" |
Research Engineer |
Session Hygiene & Context Recovery
- BUILD_STATUS.md updates on
main only, not feature branches
- Fresh session after each merge
- 4 git commands for full context:
git branch + git diff main...HEAD --stat + git diff main...HEAD + git status
- Branch naming:
feature/{subproject}/L{N}-{name}
New Project Setup
- Write TECH_SPEC.md, SCREEN_SPEC.md, BUILD_STATUS.md
- Write CLAUDE.md with auto-routing
- Create
.claude/agents/ (pm, dev, qa, research)
- Create
.claude/skills/[project]/SKILL.md with /pst commands
- Start Layer 1
1---2name: powerhouse-software-team3description: Full AI software development team — PM plans, Dev builds, QA reviews. Use this skill when the user wants to build software with a structured pipeline, needs a PM → Dev → QA workflow, asks for spec-first development, layer-gated builds, or mentions wanting an AI dev team. Triggers include: "build me a feature", "set up a dev team pipeline", "plan then build then review", "spec-first development", "layered build order", "I need PM Dev QA agents", "agent pipeline for software", or any mention of structured software development with role separation. Also trigger when the user asks for ticket-based development, build status tracking, or context recovery across sessions. Spec-first, layer-gated, 7-point QA validation, context recovery. Commands: /pst status, /pst plan, /pst build, /pst review, /pst branch, /pst pr, /pst next4---56# Powerhouse Software Team78## Overview910Run a complete AI software development team: PM plans, Dev builds, QA reviews — all gated by spec documents and a strict layer build order.1112**Core principle:** No code without a spec. No Layer N without Layer N-1 complete.1314**Target:** Claude Code, OpenCode, Kimi Code. Works in both single-project repos and monorepos.1516---1718## The Three Anchor Documents1920Write these **before any code**. They are contracts, not documentation:2122| Document | Purpose |23|----------|---------|24| TECH_SPEC.md | Data contract — schemas, collections, service signatures |25| SCREEN_SPEC.md | UX contract — every screen in ASCII or wireframe |26| BUILD_STATUS.md | Progress tracker — checkboxes per layer, updated after every merge |2728**Hard rule:** No spec = STOP. Write the spec first, then plan the ticket.2930---3132## Layered Build Order3334Enforce N-1 before N. Typical full-stack app stack:3536| Layer | Name | What goes here |37|-------|------|----------------|38| 1 | Types & Constants | Interfaces, enums, color tokens, config |39| 2 | Services | Data access — CRUD, auth, storage |40| 3 | Context & Hooks | State management, business logic |41| 4 | Base Components | Reusable UI primitives |42| 5 | Screens / Pages | Full route implementations |43| 6 | Backend Functions | Cloud functions, webhooks, scheduled jobs |44| 7 | Integration & Polish | Wire together, performance, real data |4546Adapt layer names and count to your stack. The gate rule is universal.4748---4950## Agent Pipeline (every feature)5152```53PM Tech Lead → [Research?] → Dev Engineer → QA Engineer → Human Approve → Merge54```5556| Agent | Responsibility |57|-------|---------------|58| PM Tech Lead | Plans ticket, enforces N-1 gate, defines scope + out-of-scope |59| Research Engineer | Investigates new APIs/integrations — skip for standard CRUD |60| Dev Engineer | Implements ticket exactly — no more, no less |61| QA Engineer | Validates against TECH_SPEC + SCREEN_SPEC schemas |6263Create agent files at `.claude/agents/` — one markdown file per agent with role, trigger, and output format.6465**Step 5b — Browser verification (web projects only):** After code review, the QA Engineer uses `/browse` to verify the built UI in a real browser:66- Console — no JS errors after page load67- Critical UI elements present68- Main user flow works end-to-end69- Layout holds at mobile + desktop7071Skip this step for mobile apps, CLIs, and backend-only features.7273---7475## Monorepo Support7677If your project is a monorepo with multiple sub-projects, scope all commands to the active sub-project.7879**Sub-project detection (in order):**801. User passes `--project <name>` explicitly → use it812. CWD is inside a sub-project directory → infer from path823. CWD is repo root → show root-level BUILD_STATUS.md834. Ambiguous → ask once: "Which sub-project?"8485**Implementation:**8687```python88def detect_project(args: list, cwd: str, root_path: str) -> str:89 if "--project" in args:90 idx = args.index("--project")91 return args[idx + 1]92 rel = os.path.relpath(cwd, root_path)93 parts = rel.split(os.sep)94 if parts[0] in ("mcps", "skills") and len(parts) >= 2:95 return parts[1]96 return "root"97```9899---100101## Unified Command: /pst102103| Sub-command | Action |104|-------------|--------|105| `status [--project <name>]` | Read BUILD_STATUS, current layer + next unchecked task |106| `plan [feature]` | Invoke PM Tech Lead → structured ticket |107| `build` | Invoke Dev Engineer → implement current ticket |108| `review` | Invoke QA Engineer → validate changes |109| `branch [name]` | Create `feature/{subproject}/L{N}-{name}` |110| `pr` | Type-check → rebase → push → create PR |111| `next` | Find first unchecked item across all sub-projects |112113---114115## Auto-Routing116117| User says | Action |118|-----------|--------|119| "build X", "create X", "add X" | PM Tech Lead ticket first |120| "review", "check", "QA" | QA Engineer |121| "done", "merge", "PR" | Finish-feature flow |122| "status", "what's next" | Read BUILD_STATUS |123| "research X", "how does X work" | Research Engineer |124125---126127## Session Hygiene & Context Recovery128129- BUILD_STATUS.md updates on `main` only, not feature branches130- Fresh session after each merge131- 4 git commands for full context: `git branch` + `git diff main...HEAD --stat` + `git diff main...HEAD` + `git status`132- Branch naming: `feature/{subproject}/L{N}-{name}`133134---135136## New Project Setup1371381. Write TECH_SPEC.md, SCREEN_SPEC.md, BUILD_STATUS.md1392. Write CLAUDE.md with auto-routing1403. Create `.claude/agents/` (pm, dev, qa, research)1414. Create `.claude/skills/[project]/SKILL.md` with `/pst` commands1425. Start Layer 1
bot8080