britt/project-foundations

Use when the user asks for an architecture diagram, says 'show me the system architecture' or 'diagram the components', or during project planning - generates GitHub-compatible Mermaid flowcharts showing components, layers, subgraph boundaries, and data flows

Use when asked to map issue dependencies, show what blocks what, or find the critical path through project work - reads GitHub issues for blocked-by/depends-on signals and generates Mermaid flowcharts of blocking chains

Use when writing or refining a GitHub issue that needs a cost estimate, when asked to estimate, size, budget or forecast agent spend on work, or when deciding whether an item is an issue or an epic - gives an issue a change footprint (expected lines changed and expected files read, each in a bucket) that predicts coding-agent token spend, recorded as labels, a Footprint section, and a project field

Use when writing or refining a GitHub issue, epic, or other work item that needs a size, when asked to estimate, point, or size work, or when deciding whether an item is an issue or an epic - gives an issue one story-point estimate on a powers-of-two scale (1, 2, 4, 8) and an epic the sum of its children's points, with no upper limit, recorded as a label, an Estimate section, and a project field

Use when the user says 'create issues for...', 'break this into tasks', or 'decompose this feature', or when converting a project description into GitHub issues - produces 5-15 INVEST-quality issues with user stories, acceptance criteria, dependencies, labels, and powers-of-two point estimates

Use when creating any Mermaid diagram (flowchart, sequence, class, state, ER, Gantt) in markdown, or when a diagram fails to render on GitHub - covers the syntax rules that break GitHub rendering (parentheses in labels, mismatched brackets) plus per-type examples

Use when starting work on an unfamiliar codebase or asked to 'analyze this project' - maps structure, project type, architecture pattern, key files, and dependencies into a standard report

Use when a repo's agent setup may be broken, half-finished, or drifted - a setting-up-a-project run failed partway, CLAUDE.md or AGENTS.md is thin or missing sections, leftover {{PLACEHOLDER}} text, AGENTS.md is a symlink, the instruction files disagree, or agents behave inconsistently in the repo - audits the project against what setting-up-a-project would generate today and repairs only the gaps, preserving existing content

Use when setting up a new project for coding agents, when a repo has no CLAUDE.md or AGENTS.md, or when starting work on an empty codebase - surveys the repo, interviews the user, and authors CLAUDE.md plus an AGENTS.md tuned for Codex CLI, OpenCode, and Cursor, covering project purpose, tech stack, commands, TDD rules, and development practices

Use when asked to dispatch Conductor workspaces for a list of issues and then watch them until their PRs merge - "dispatch workspaces for issues 310-315 and monitor them", "keep the open PRs up to date with main", "tell green PRs to merge", "archive workspaces once their PR merges", "babysit the open PRs". Spins up one Conductor workspace per issue, runs a poller over the repo's open PRs, nudges owning agents when their PR falls behind the base branch, resolves merge conflicts, reruns transient CI failures, tells green PRs to merge, and archives each workspace once its PR lands. Not for implementing a single issue or coordinating the children of one epic. Works for any GitHub repo; uses the conductor and gh CLIs.

Use when asked to dispatch Paradev workspaces for a list of issues and then watch them until their PRs merge - "dispatch workspaces for issues 310-315 and monitor them", "keep the open PRs up to date with main", "tell green PRs to merge", "archive workspaces once their PR merges", "babysit the open PRs". Spins up one Paradev workspace per issue, runs a poller over the repo's open PRs, nudges owning agents when their PR falls behind the base branch, resolves merge conflicts, reruns transient CI failures, tells green PRs to merge, and archives each workspace once its PR lands. Not for implementing a single issue or coordinating the children of one epic. Works for any GitHub repo; uses the paradev and gh CLIs.

Use when asked to work on, implement, drive, or coordinate a GitHub epic, parent issue, or tracking issue whose work is split into child issues, and separate agent workspaces are available to implement them - you coordinate, the children implement

Use when asked to work on, read, or implement a GitHub issue - hands-off workflow (understand, scoped recon, verification plan, implementation plan, implement, verify, PR) with no mid-flow approval gates; assumptions are documented in the plan and PR, and developer review happens on the pull request

Use when asked to write user stories, define requirements, break a feature into stories, or draft product/feature issues - produces stories in "As a [persona], I want [action], so that [benefit]" format with Given-When-Then acceptance criteria and an INVEST quality checklist

Use when a project lacks VERIFICATION_PLAN.md, when finishing setting-up-a-project, or when asked how to prove a feature works end-to-end - writes real-system acceptance scenarios (no mocks) with success criteria and a pass/fail verification log