Stackmoss
AGENTS.md4 starsChanged 8 months agoMITView on GitHub
StackMoss is a CLI pipeline that generates and maintains agent team configurations for AI coding assistants. It creates roles, governance, and skill files so every AI agent shares project context. Every command MUST call validateState() before executing. Compiled outputs are generated — do NOT edit them manually. Edit team.md instead. No git add . — stage files explicitly by path.
- Deletes or force-pushes
- Commits and pushes
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,542 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- cli-pipelineSkill
- intake-engineSkill
- stretch-testingSkill
- template-engineSkill
- skill-creatorSkill
The file
We split this AGENTS.md into the rules it gives an agent
8 rules. About 1 is common, 2 are distinctive, and 5 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 24
MIGRATING: Read-only on repo, write only to .agents/, no code execution
- Very specific: line 27
Every command MUST call validateState() before executing.
- Very specific: line 64
Always run npm test after modifying TypeScript files.
- Very specific: line 65
Run npm run build before committing to verify compilation.
- Very specific: line 66
Use npm (not yarn, not pnpm) for dependency management.
- Distinctive: line 67
Ask for confirmation before adding new production dependencies.
- Distinctive: line 73
Atomic writes: All file generation uses temp→rename pattern.
- Common: line 76
Secret hygiene: Never persist tokens, passwords, API keys, credentials, or private keys in config, generated instructions, logs, or patch …
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.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.
Files
AGENTS.md — StackMoss
Project Overview
StackMoss is a CLI pipeline that generates and maintains agent team configurations for AI coding assistants. It creates roles, governance, and skill files so every AI agent shares project context.
- Runtime: Node.js ≥18 · TypeScript (strict, ES2022)
- Package manager: npm
- Test framework: Vitest
- CLI framework: Commander.js
- Entry point:
src/bin/stackmoss.ts - Authority: runtime behavior must stay aligned across
src/, generated outputs, and tests.
State Machine (BRD §6)
GLOBAL ──[inject]──▶ MIGRATING ──[resolve + promote]──▶ OPERATIONAL
│
[upgrade] CONSTITUTION-only merge
[patch apply] replace-only + budget gate- GLOBAL: Template-only, no project knowledge
- MIGRATING: Read-only on repo, write only to
.agents/, no code execution - OPERATIONAL: Research locked, learn from operational experience only
Every command MUST call validateState() before executing.
CLI Commands (BRD §7)
| Command | Phase | State Required |
stackmoss new <name> | A | Any |
stackmoss inject | B | GLOBAL |
stackmoss resolve | B | MIGRATING |
stackmoss promote --confirm | B | MIGRATING |
stackmoss run <alias> | C | OPERATIONAL |
stackmoss check | C | OPERATIONAL |
stackmoss patch apply/reject | C | OPERATIONAL |
stackmoss upgrade | C | OPERATIONAL |
BRD Roles → Agent Mapping
| BRD Role | Codex Agent | Trigger |
| [TL] Tech Lead | tech-lead | Architecture, feature breakdown, review, CONTEXT.md/FEATURES.md |
| [DEV] Developer | dev | Implementation, env commands, debug |
| [QA] Quality Assurance | qa | Tests, acceptance criteria, regression, word budget |
| [SEC] Security-lite | security-auditor | Auth, PII, financial data features |
Compile Targets (BRD §15)
| Target | Split Level | Output Path |
| Claude Code | Role-level (1 role = 1 file) | .claude/skills/ |
| Cursor / Roo | Role-level | .cursor/skills/, .roo/skills/ |
| Codex | Role-level + repo guidance | AGENTS.md + .agents/skills/ |
| Antigravity | Role-level + shared rules/workflows | .agent/{skills,rules,workflows} |
Compiled outputs are generated — do NOT edit them manually. Edit team.md instead.
Working Agreements
- Always run
npm testafter modifying TypeScript files. - Run
npm run buildbefore committing to verify compilation. - Use
npm(not yarn, not pnpm) for dependency management. - Ask for confirmation before adding new production dependencies.
Architecture Rules (BRD §3)
- Deterministic logic only: Pack/role selection, persona detection — never LLM.
- Replace-only + word budget: Config never grows. Team total max: 1800 words.
- Atomic writes: All file generation uses temp→rename pattern.
- No silent assumptions: Unknown →
OPEN_QUESTIONS.md. Never infer critical decisions. - Safe by default: Suggest-only mode. Forbid
rm -rf,drop table,git push --force. - Secret hygiene: Never persist tokens, passwords, API keys, credentials, or private keys in config, generated instructions, logs, or patch proposals.
Commit Hygiene (A/B/C Layers)
| Layer | Scope | Prefix |
| A | Feature code (src/, tests/) | feat():, fix():, refactor(): |
| B | Reports / logs | chore(report):, test(result): |
| C | Documents (*.md, .agents/) | docs(): |
No git add . — stage files explicitly by path.
Language Boundary
| Context | Language |
| Human-facing communication | Vietnamese |
| Code, CLI output, commit messages | English |
| BRD, FEATURES.md, NORTH_STAR.md | Vietnamese |
| SKILL.md, workflow instructions | English |
Source Structure
src/
├── bin/stackmoss.ts # CLI entry (shebang)
├── commands/ # new, inject, resolve, promote, run, check, patch, upgrade
├── intake/ # Fast (7Q) + Interview (13Q) modes
├── templates/ # 7 output file generators
├── compile/ # ClaudeCode, Cursor, Antigravity, Codex, VS Code compile targets
├── scanner/ # Repo scanner + migration report
├── patch/ # Patch proposal engine
├── budgets.ts # Canonical word budget source (BRD §12.4)
├── config.ts # Config schema + factory
└── state-machine.ts # 3-state machine + validationSkills
Skills in .agents/skills/, each with SKILL.md + agents/openai.yaml + references/:
cli-pipeline— CLI commands, state machine, pipeline orchestrationintake-engine— Onboarding questionnaire, pack selection, completeness gatestemplate-engine— Output file generation, compile layer, schema validationstretch-testing— Adversarial QA, BRD mismatch detection, edge case probing
Workflows
In .agents/workflows/, invoke with /slash-command:
/feature-cycle— Full feature cycle from TODO to DONE/new-command— Scaffold a new CLI command/new-template— Create or update an output template/qa-check— QA verification checklist
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
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.