agentic-workflow CLAUDE.md

CLAUDE.md

Guidance for AI coding agents working in this repository (agentic-workflow).

This repo is not an application. It ships two things:

1. skills/ — a stack-agnostic set of agent skills that run a disciplined, doc-driven feature/issue workflow. Each is one skills/<name>/SKILL.md.
2. template/ — an exportable documentation scaffold: the way of working (documentation map, SPEC/feature/fix templates, GitHub templates, conventions) that a target project copies so the skills have a substrate to operate on.

The skills are project-adaptive: at runtime they discover and obey the target project's own guide, documentation map, architecture, roadmap and style docs. Nothing here is tied to a specific stack, framework, or architecture pattern.

---

Repository layout

skills/                  the workflow skills (one SKILL.md each) — the installable source
.claude/skills           symlink → ../skills, so this repo dogfoods them in Claude Code
template/                the exportable documentation scaffold (generic, copyable)
packages/                two companion npm packages (bun-managed islands — see Packages below)
docs/workflow/           the tutorial: feature flow, issue flow, skill reference, replication
docs/features/_TEMPLATE  feature SPEC template + ROADMAP
docs/fix/                fix SPEC template + index
.github/                 issue + PR templates the workflow expects
README.md / README.es.md project overview (EN / ES)

---

Working rules

• Docs language is English. Every committed artifact (skills, docs, templates, commits, PR descriptions) is in English, regardless of the language used to request the work. Reply to the user in the user's language.
• Human-readable docs carry EN + ES siblings. README, CHANGELOG, docs/workflow/*.md, and the schema package README each get a faithful .es.md sibling with reciprocal language-switcher links (> 🇪🇸 [Versión en español](<name>.es.md) on the English original, > 🇬🇧 [English version](<name>.md) on the Spanish sibling). Hard rule — the ES sibling is updated in the SAME change, never deferred. If a change edits an English doc that has a .es.md sibling (or is documentation that should be translated), it MUST update the Spanish version in the same commit/PR — a diff that touches only the English side of a bilingual pair is incomplete and must not be committed or merged. This is not "on next touch, best effort": whoever edits the English doc owns the reciprocal ES edit right then. There is no automated staleness check, so the rule is enforced by the author and by review. Scope exception: SKILL.md, SPECs, commits, PRs, and machine config (model-routing.yml) stay English-only per the docs-language rule above and have no ES sibling — the bilingual sync rule applies only to docs that actually have a translatable sibling (human tutorial/reference prose), never to process artifacts.
• Stack/architecture agnostic. Do not introduce references to any specific product, stack, framework, ORM, runtime, or architecture pattern into the skills or the shared docs. Generic phrasing ("the project's architecture", "the project's verification gate") is the rule.
• One PR per unit of work, always against main. Never work on main directly; never stack PRs (a PR's base is always main).
• Commit format: conventional commits, e.g. feat(skills): add execute-phase, docs(workflow): clarify replicate steps, chore(template): add brand stub.