Update References
Ensure naming and documentation consistency across all codebase locations.
Checklist
When updating terminology, feature names, descriptions, or counts, check ALL locations:
1. User-Facing Messages
| Location | What to Check |
|---|
launcher/banner.py | Welcome banner text, feature descriptions |
launcher/cli.py | Pilot CLI help text and messages |
installer/cli.py | Installer CLI help text, prompts |
installer/steps/finalize.py | Post-install instructions |
installer/ui.py | UI banner and status messages |
2. Documentation & Website
| Location | What to Check |
|---|
README.md | Feature descriptions, usage examples, counts (rules, hooks, skills, commands) |
docs/site/index.html | SEO meta tags, page title, structured data |
docs/site/src/pages/Index.tsx | SEO description, structured data counts |
docs/site/src/components/HeroSection.tsx | Stats bar counts (rules, hooks, skills, LSPs, MCP) |
docs/site/src/components/WhatsInside.tsx | Feature cards, descriptions, item counts |
docs/site/src/components/DeepDiveSection.tsx | Under the Hood subtitle counts, hooks pipeline, rules categories |
docs/site/src/components/WorkflowSteps.tsx | /spec workflow details, All Commands grid |
docs/site/src/components/ComparisonSection.tsx | Before & After comparison table |
docs/site/src/components/PricingSection.tsx | Standard plan feature counts, value proposition |
docs/site/src/components/InstallSection.tsx | Installation instructions |
docs/site/src/components/Footer.tsx | Footer links |
docs/site/src/components/NavBar.tsx | Navigation links |
3. Package & Install
| Location | What to Check |
|---|
pyproject.toml | Package name, description, metadata |
install.sh | Shell installer script messages |
launcher/__init__.py | Package docstring |
4. Claude Configuration (Plugin Source)
| Location | What to Check |
|---|
pilot/commands/*.md | Command descriptions in frontmatter (spec, sync, vault, learn, plus internal phases) |
pilot/skills/*/SKILL.md | Skill descriptions in frontmatter |
pilot/rules/*.md | Standard rules content |
pilot/hooks/hooks.json | Hook configuration and event triggers |
pilot/hooks/*.py | Hook script messages and logic |
pilot/agents/*.md | Sub-agent definitions (plan-verifier, spec-verifier) |
pilot/settings.json | LSP server configuration |
pilot/modes/*.json | Language mode definitions |
5. Project-Level Claude Config
| Location | What to Check |
|---|
.claude/rules/*.md | Project-specific rules (git-commits.md, project.md) |
.claude/skills/*/SKILL.md | Project-specific skills (lsp-cleaner, pr-review, update-refs) |
No Hardcoded Counts
Do NOT add specific counts (e.g., "22 rules", "7 hooks", "14 skills") to user-facing text.
The project deliberately avoids quantity-focused messaging. Use qualitative descriptions instead:
| ❌ Don't | ✅ Do |
|---|
| "22 rules loaded every session" | "Production-tested rules loaded every session" |
| "7 hooks auto-lint on every edit" | "Hooks auto-lint, format, type-check on every edit" |
| "14 coding skills" | "Coding skills activated dynamically" |
| "5 MCP servers + 3 LSP servers" | "MCP servers + language servers pre-configured" |
| "2,900+ lines of best practices" | "Production-tested best practices" |
Why: Quality over quantity. Counts become stale and create maintenance burden across many files. The value is in what the system does, not how many components it has.
Workflow
- Search first - Use Grep to find all occurrences:
Grep pattern="old term" glob="*.{md,py,tsx,json,ts}" - Update systematically - Work through checklist above, section by section
- Verify consistency - Search again to confirm no misses:
Grep pattern="old term" glob="*.{md,py,tsx,json,ts}" - Build website - Verify site compiles after changes:
cd docs/site && npm run build
Common Updates
| Change Type | Key Locations |
|---|
| Command rename/add | pilot/commands/*.md, README.md, WorkflowSteps.tsx, WhatsInside.tsx, counts table |
| Skill rename | pilot/skills/*/SKILL.md, README.md, WhatsInside.tsx, DeepDiveSection.tsx |
| Rule add/remove | pilot/rules/*.md, README.md, all count locations (see table above) |
| Hook change | pilot/hooks/hooks.json, pilot/hooks/*.py, DeepDiveSection.tsx, README.md |
| Feature description | launcher/banner.py, README.md, site components, Index.tsx structured data |
| Workflow change | pilot/commands/*.md, pilot/rules/*.md, README.md, WorkflowSteps.tsx |
| Package rename | pyproject.toml, install.sh, launcher/init.py, README.md |
| Installer message | installer/*.py, installer/steps/*.py |
| Terminology change | Search all locations in checklist above — grep for old term, replace everywhere |
