r-bart scribetronic-help
Orientation skill for AI agents working ON the scribetronic codebase itself (not for projects scaffolded BY scribetronic). Loads the project layout, CLI surface, skill inventory, contracts, and quality command in one shot.
When to Use
- First turn of a new session on this repo.
- An agent is about to make changes and needs a map.
- You're unsure where a feature lives or which file to edit.
What scribetronic Is
A TypeScript ESM CLI that scaffolds AI-assisted project setups. It analyzes a target project, then writes CLAUDE.md, .claude/rules/, and a curated set of skills tailored to the stack.
Top-Level Layout
The authoritative folder map lives in docs/ARCHITECTURE.md. Read it before navigating the tree. Quick reference:
scribetronic/
├── packages/cli/
│ ├── src/ ← CLI source: commands/, analyzers/, generators/, data/
│ ├── templates/
│ │ ├── claude-code/ ← Distributed `.claude/` payload (skills, rules, settings)
│ │ └── project/ ← Distributed project files (CLAUDE.md, docs/)
│ └── package.json
├── docs/
│ ├── ARCHITECTURE.md
│ └── contracts.md ← Shared contracts between modules and templates
├── thoughts/ ← Plans, notes, state
└── .claude/ ← THIS directory: rules and help for working on scribetronic itself
Important distinction:
.claude/(this dir) — used when developing scribetronic. Not distributed.packages/cli/templates/claude-code/.claude/— what end users get. Distributed.
CLI Commands (high level)
The CLI exposes 4 top-level commands. See packages/cli/src/commands/ for entry points.
| Command | Purpose |
|---|---|
init |
First-time setup in a project. Analyzes the stack, writes CLAUDE.md, rules, and the default skill set. |
add |
Add an individual skill, rule, or template to an already-initialized project. |
update |
Pull updated templates and migrate existing project files to the latest schema. |
doctor |
Diagnose an existing setup — detect drift, broken references, outdated skills. |
Read the actual source under packages/cli/src/commands/ for current flags and behavior — this table is a map, not a contract.
The 21 Skills
The skill bundle distributed to end-user projects lives under:
packages/cli/templates/claude-code/.claude/skills/
Each skill is a folder containing a SKILL.md with YAML frontmatter (name: must equal the folder name) plus any supporting files. When editing skills, remember they target end-user projects — not this repo.
Contracts
Shared contracts between modules (analyzers ↔ generators, generator ↔ template, skill ↔ config key) are documented in docs/contracts.md. Always read it before:
- Renaming a field consumed across module boundaries.
- Adding a new template that another generator will reference.
- Changing a skill's config key (skills must read keys from config, never hardcode).
Quality Command
Run from repo root or wherever — it cd's into the CLI package:
cd packages/cli && npm run typecheck && npm run lint && npm test
Add && npm run build when verifying the publishable artifact.
Full quality rules: .claude/rules/quality.md.
Architecture rules: .claude/rules/architecture.md.
Recommended First Moves
- Read
docs/ARCHITECTURE.md. - Read
docs/contracts.mdif your change crosses module boundaries. - Skim
packages/cli/src/commands/to find the entry point closest to your task. - Run the quality command once to confirm a clean baseline before editing.