davidmatousekdavidmatousek/tachi/CLAUDE.md

tachi

CLAUDE.md95 starsChanged 36 days agoApache-2.0View on GitHub

Note: Template provides methodology only. Users bring their own code. Post-init (recommended after make init): - /aod.foundation — Guided workshop: product vision + design identity Triad workflow: - /aod.define → /aod.plan → /aod.build [--no-security] [--no-design-check] [--no-economy] - (/aod.plan chains: spec → project-plan → tasks automatically) Post-delivery: - /aod.deliver — Close completed feature - /aod.document [--autonomous] — Quality review: simplify, docstrings, CHANGELOG, API docs (--autonomous for orchestrator-driven runs) Downstream Updates (adopter-side template sync): - /aod.update — Apply upstream PLSK template updates…

In this repository30 other files it gives its agents.
- ~aod-blueprintSkill
- ~aod-bugfixSkill
- ~aod-buildSkill
- ~aod-defineSkill
- ~aod-deliverSkill
- ~aod-discoverSkill
- aod-foundationSkill
- ~aod-kickstartSkill
- aod-lensSkill
- aod-orchestrateSkill
- ~aod-planSkill
- ~aod-project-planSkill
- ~aod-runSkill
- ~aod-scoreSkill
- ~aod-specSkill
- aod-stackSkill
- ~aod-statusSkill
- code-execution-helperSkill
- git-workflow-helperSkill
- kb-createSkill
- kb-querySkill
- root-cause-analyzerSkill
- securitySkill
- tachi-control-analysisSkill
- tachi-infographicsSkill
- tachi-orchestrationSkill
- tachi-report-assemblySkill
- tachi-risk-scoringSkill
- tachi-sharedSkill
- tachi-threat-reportingSkill

The file

We split this CLAUDE.md into the rules it gives an agent

10 rules. About 0 are common, 6 are distinctive, and 4 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Product-Led: Start with product vision, PRDs, and user stories
line 6
Very specific:
Validation Required: Run /aod.analyze before PRs
line 8
Very specific:
Local-First: Always supports local .aod/ file workflows
line 9
Distinctive:
Never commit to main directly
line 14
Distinctive:
All deployments must go through the devops agent.
line 87
Distinctive:
When invoked as a subagent (via Agent tool), return ONLY:
line 90
Distinctive:
Write detailed findings to results file BEFORE returning
line 94
Distinctive:
NEVER return code snippets, file contents, or multi-paragraph explanations
line 96
Very specific:
Use make review-spec or make review-plan for manual governance checks
line 109
Very specific:
Search docs/core_principles/ for thinking methodologies
line 110

≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

CLAUDE.md

CLAUDE.md - tachi

Core Constraints

Product-Led: Start with product vision, PRDs, and user stories
Source of Truth: .aod/spec.md
Validation Required: Run /aod.analyze before PRs
Local-First: Always supports local .aod/ file workflows

Git Workflow

Always use feature branches: git checkout -b NNN-feature-name

NNN = GitHub Issue number, zero-padded to 3 digits
Never commit to main directly
Draft PR opened at plan stage, marked ready at delivery
Branch format: NNN-descriptive-name (e.g., 021-feature-name for Issue #21)

Project Structure

tachi/
├── .claude/           → Agents, skills, commands, design archetypes
├── .aod/              → Active feature workspace (spec.md, plan.md, tasks.md)
├── brands/            → Brand identity assets (vision + design tokens)
├── specs/             → Archived feature artifacts (per-feature history)
├── docs/              → Product, architecture, devops docs
├── scripts/           → init.sh, check.sh
├── stacks/            → Stack packs (conventions, personas, scaffolds)
└── CLAUDE.md          → AI agent context

Note: Template provides methodology only. Users bring their own code.

Context Discovery

Thinking Lenses: docs/core_principles/README.md (5 Whys, Pre-Mortem, etc.)
Project Standards: docs/standards/README.md (DoD, naming, git)
Product Docs: docs/product/README.md
Architecture: docs/architecture/README.md
Triad Guide: docs/AOD_TRIAD.md
Constitution: .aod/memory/constitution.md

Commands

PDL workflow (optional, before Triad):

/aod.discover → /aod.score

Post-init (recommended after make init):

/aod.foundation — Guided workshop: product vision + design identity

Triad workflow:

/aod.define → /aod.plan → /aod.build [--no-security] [--no-design-check] [--no-economy]
(/aod.plan chains: spec → project-plan → tasks automatically)

Post-delivery:

/aod.deliver — Close completed feature
/aod.document [--autonomous] — Quality review: simplify, docstrings, CHANGELOG, API docs (--autonomous for orchestrator-driven runs)

Downstream Updates (adopter-side template sync):

/aod.update — Apply upstream PLSK template updates to your project. Direction: PLSK → user. See docs/guides/DOWNSTREAM_UPDATE.md.
/aod.sync-upstream — Push local template improvements back to the public PLSK repo. Direction: user → PLSK.

Terminology: sync-upstream = user → PLSK (contribute back). update = PLSK → user (pull updates). These are opposite-direction commands — do not confuse them.

Supporting commands:

/aod.clarify — Resolve spec ambiguities
/aod.analyze — Cross-artifact consistency check
/aod.checklist — Generate quality checklist
/aod.constitution — Manage governance principles
/aod.kickstart — POC kickstart: generate consumer guide with seed features
/aod.blueprint — Multi-feature story generation from consumer guide
/aod.status — View backlog and lifecycle stage summary
/aod.roadmap — Scaffold quarterly roadmap from completed PRDs
/aod.okrs — Scaffold OKR document with standard template
/aod.stack — Manage stack packs (activate, remove, list, scaffold)

SDLC Triad Governance

Role	Defines	Authority
PM	What & Why	Scope & requirements
Architect	How	Technical decisions
Team-Lead	When & Who	Timeline & resources

Sign-off Requirements:

spec.md: PM sign-off
plan.md: PM + Architect sign-off
tasks.md: PM + Architect + Team-Lead sign-off

Deployment Policy

All deployments must go through the devops agent. Never deploy without verification.

Subagent Return Policy

When invoked as a subagent (via Agent tool), return ONLY:

Status (APPROVED / CHANGES_REQUESTED / BLOCKED / pass / fail)
Item count (if applicable)
File path to .aod/results/{agent-name}.md with full details

Write detailed findings to results file BEFORE returning
Max return: 15 lines / ~200 tokens
NEVER return code snippets, file contents, or multi-paragraph explanations
Policy applies to subagent→main returns only, not user-facing output

Key Principles

Vision First: /aod.define (includes vision) → /aod.plan (spec → plan → tasks)
Triple Sign-off: PM + Architect + Team-Lead approval on tasks.md
Definition of Done: 3-step validation before marking complete

Context Boundaries

EXCLUDE: archive/, node_modules/, .git/, *.log FOCUS: .aod/, docs/, .claude/, current feature branch

Tips

Use make review-spec or make review-plan for manual governance checks
Search docs/core_principles/ for thinking methodologies
Review agent-assignments.md for workload distribution

Recent Changes

See CHANGELOG.md for the full release history. Read it directly when feature context is needed — do not duplicate entries here.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free