my-tech-lead-flow

Generate the project CLAUDE.md as a dense, agent-facing operating manual in the Terral/Tatanan format, at the end of the documentation pipeline just before build starts. Distills the technical specs, coding standard, task breakdown, and deployment plan into the rules an agent must hold in context: tech stack, repo layout, architecture laws (file-size cap and split strategy, layering), runtime do/don't, the verification gate, naming, type-safety, prohibitions, a context-recovery checklist, and a command quick-reference. Use when the user wants to initialize or write CLAUDE.md, an agent operating manual, AGENTS.md, or asks to "init claude".

Use after completing a task when all verifications pass. Covers verification commands, splitting into logical commits, explicit file staging, Conventional Commits format with 80-char line cap, no `@` mentions in messages, no Co-Authored-By trailers, and creating GitHub releases (version-only title, signed tag pushed before `gh release create`, CHANGELOG-only notes).

Produce the api-specs/ document set (numbered NN-topic.md files plus _index.md) from the technical specs, in the Terral/Tatanan format. Derives every operation, its inputs/outputs, errors, and access rules from the module definitions and data model already decided in docs/technical-specs/, and writes them in whatever protocol the project chose — REST, GraphQL, gRPC, or SOAP. Use when the user wants an API specification, endpoint contracts, an OpenAPI/schema/proto/WSDL companion, or asks to "write the api specs". Runs after technical-spec and before task-breakdown.

Scaffold a new project as the Tech Lead would in Sprint 0, after the task breakdown and before coding standards are written. Grills on folder structure, architectural patterns, commit hooks, tooling, and stubs, then executes the scaffold: directory layout, tooling config, pre-commit hooks, and endpoint/page stubs that return mock responses so frontend and backend can build in parallel from day one. Use when the user wants to set up, bootstrap, or scaffold a project, stand up the repo skeleton, do Sprint 0, or asks to "set up the project".

Produce the technical-specs/ document set (numbered NN-topic.md files plus _index.md) from the groomed business docs, in the Terral/Tatanan format. Grills the user on tech stack and tooling first — this is the architectural keystone the rest of the pipeline depends on — then writes overview, architecture, repo structure, tech stack, module definitions, data model, security, NFRs, auth, integrations, environment config, and ad-hoc trailing specs for areas that need special technical attention. Use when the user wants a technical specification, TSD, architecture/data-model doc, or asks to "write the technical specs".

Groom a set of user stories and acceptance criteria from the technical team's perspective, surfacing every gap engineering needs closed before committing to the work. Runs in two modes — blast all questions into a file with recommendations (for taking to a BA/PO in a refinement meeting), or interview the user one question at a time and then refine the US/AC from their answers (for a TL who captured the requirements himself). Use when the user wants to refine a backlog item, prepare for sprint grooming/refinement, sanity-check a story before estimation, or asks to "groom this story".

Optional pre-pipeline skill for when there are no user stories or acceptance criteria yet. Interviews the user about a raw product idea, then synthesizes the result into the Markdown table of user stories, acceptance criteria, and a sprint breakdown that the rest of the tech-lead pipeline (grooming, us-ac-formatter) consumes as its step-1 input. Use when the user has an idea but no written requirements, wants to start a project from scratch, says "I don't have user stories yet", "help me figure out the requirements", "turn this idea into stories", or asks where to begin.

Author a project's CODING_STANDARD.md and CODE_REVIEW_CHECKLIST.md by inferring the conventions already present in the codebase, then filling gaps with sensible defaults the user confirms. Language- and stack-agnostic. Produces standards a reviewer can cite verbatim and a checklist a reviewer can walk item by item — the inputs the /code-review skill consumes. Use when the user wants to write, generate, or formalize coding standards, a style guide, or a code review checklist for a repo.

Act as the Tech Lead and break a set of user stories + acceptance criteria into a sprint-by-sprint, role-assigned task board in the project's TASK_BREAKDOWN.md format. Reads docs/business first, asks for team size and roles, splits work into Backend/Frontend cards, and — critically — makes frontend↔backend wiring its own explicitly-owned card. Use when the user wants to break work into sprint cards, plan a sprint board, assign tasks to engineers, or asks to "break this down into tasks".

Produce a DEPLOYMENT_PLAN.md operational runbook by first grilling the user on infrastructure, environments, secrets, release flow, and rollback until every gap is resolved, then writing the document. Models the Tatanan/Terral deployment plan — environments, infra overview, initial deploy, release updates, rollback, and a database debugging cookbook with copy-paste commands. Use when the user wants a deployment plan, deployment runbook, ops/release documentation, or asks to "write a DEPLOYMENT_PLAN".

Act as a tech lead reviewing a pull request against the project's own coding standards and review checklist, in any language. Discovers the repo's standards docs, checks out the PR branch in an isolated git worktree, runs the project's test / lint / format / type-check gates, verifies the diff against the checklist and any referenced acceptance criteria, then posts a structured review with severity-tagged findings. Use when the user asks to review a PR, review a branch, or do code review.

Stand up the GitHub project from the task breakdown, after coding standards are set. Converts every TASK_BREAKDOWN card into an issue (assigned to the right teammate, labelled, milestoned per sprint, placed in the board Backlog), creates the Projects v2 Kanban board, the dev/test/main branches with protection, issue and pull-request templates, CI quality and build workflows, dependabot, and a release template. Asks each role (TL, BE1, FE1, ...) for their GitHub username first. Use when the user wants to initialize a GitHub project, create issues from the task breakdown, set up the kanban board, repo templates, branches, or CI workflows.

Author the orientation document set that gets a newcomer (human or agent) productive — README.md, GLOSSARY.md, DEVELOPMENT_SCENARIO_GUIDE.md, and ONBOARDING_GUIDE.md — by reading the codebase and existing project docs, then writing what is actually true. Produces any subset the user asks for; cross-links the other docs (CODING_STANDARD, TASK_BREAKDOWN, DEPLOYMENT_PLAN, etc.) instead of duplicating them. Use when the user wants a README, glossary, onboarding guide, development/getting-started guide, or "the orientation docs" for a repo.

Convert user stories and acceptance criteria pasted as a markdown table into the project's Gherkin (Given/When/Then) format, grouped by sprint goal. Use when the user pastes a US/AC table and wants it reformatted into per-sprint Gherkin acceptance-criteria docs, or asks to "format these user stories", "turn this table into Gherkin", or "break these AC down by sprint".

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

Remove AI writing patterns from prose. Use when drafting, editing, or reviewing text to eliminate predictable AI tells.

Produce a TROUBLESHOOTING.md guide organized by symptom. With no real incident corpus yet, it grills the user to map the system's architecture and seams (DB, cache, proxy, external APIs, auth, build/deploy), then scaffolds the likely failure modes at each seam as a living skeleton to grow as real incidents land. References DEPLOYMENT_PLAN.md rather than duplicating it. Use when the user wants a troubleshooting guide, runbook of common problems, an ops FAQ, or asks to "write a TROUBLESHOOTING".