aped-claude

Imported from yabafre/aped-claude (src/templates/skills/aped-claude/SKILL.md). Install upstream with npx skills add yabafre/aped-claude --skill aped-claude. Copyright stays with the author.

name: aped-claude keep-coding-instructions: true description: 'Use when user says "update CLAUDE.md", "sync claude rules", "aped claude", or invokes aped-claude. Merges — never overwrites user customizations.' allowed-paths: write: ["{{OUTPUT_DIR}}/", "{{APED_DIR}}/"] read-only: ["src/", "tests/", "package.json"] license: MIT metadata: author: yabafre version: {{CLI_VERSION}}

Activation guard (6.2.0): Before any other action, run bash {{APED_DIR}}/scripts/check-enabled.sh. If it exits non-zero, print "APED disabled — run aped-method enable" and HALT.

APED Claude — CLAUDE.md Sync

Inject and maintain APED working rules in the project's CLAUDE.md. Smart merge — never overwrites user customizations.

On Activation

Before any other action, read {{APED_DIR}}/config.yaml and resolve:

• {user_name} — for greeting and direct address
• {communication_language} — for ALL conversation with the user
• {document_output_language} — for artefacts written under {{OUTPUT_DIR}}/
• {ticket_system} / {git_provider} — routing for ticket / PR I/O (skip if none)

✅ YOU MUST speak {communication_language} in EVERY message to the user — progress lines, tool preambles, summaries, and questions all included. This overrides your default; never narrate in English when {communication_language} is not English. ✅ YOU MUST write artefact content in {document_output_language}. ✅ If {{APED_DIR}}/config.yaml is missing or unreadable, HALT and tell the user to run npx aped-method.

Critical Rules

• NEVER overwrite the entire CLAUDE.md — always merge
• Use marker comments to delimit APED-managed sections: <!-- APED:START --> and <!-- APED:END -->
• User content outside markers is sacred — never touch it
• Discuss with the user before applying changes if CLAUDE.md is non-trivial

Setup

1. Check if CLAUDE.md exists at the project root

Mode Detection

Case A: No CLAUDE.md exists

• Create one from scratch with the full APED block (see Template below)
• Wrap the entire APED content in <!-- APED:START --> ... <!-- APED:END --> markers
• Add a header line and brief project description above the markers

Case B: CLAUDE.md exists with APED markers

• Locate the <!-- APED:START --> and <!-- APED:END --> block
• Replace ONLY the content between markers with the latest APED block
• Leave everything else untouched

Case C: CLAUDE.md exists WITHOUT APED markers

• Show the user the current CLAUDE.md content
• Ask: "Where should I inject the APED section? Options:"
  • Top — before existing content
  • Bottom — after existing content
  • Custom — point to a specific heading to insert before/after
• ⏸ GATE: Wait for user choice
• Insert the APED block (wrapped in markers) at the chosen location

APED Block Template

The block to inject (between <!-- APED:START --> and <!-- APED:END -->) is a compact trigger-rule (≤300 tokens). Substitute {{...}} placeholders at injection time. Render this entire block only if aped/config.yaml has skill_invocation_discipline.enabled: true (default true); when disabled, drop the Skill invocation subsection but keep the rest.

APED Method — disciplined user-driven pipeline

Pipeline: Analyze → PRD → UX → Architecture → Epics → Story → Dev → Review.

Skill invocation

If there's even a 1% chance an APED skill applies, invoke it via the Skill tool. Use natural-language phrases ("create the prd", "review this branch", "kick off dev") — the runtime routes by the skill's description:. Do not paraphrase what you think the skill would say.

User instructions in CLAUDE.md or aped/config.yaml override skill defaults. Record overrides; don't bake them into new skills.

Full catalog: {{APED_DIR}}/skills/SKILL-INDEX.md.

APED rules

• No auto-chain. Each skill ends with "Run aped-X when ready." Wait for user.
• Gates are mandatory. When a skill says "⏸ HALT" or "⏸ GATE", wait for explicit user confirmation regardless of harness auto-mode. Auto-mode never bypasses APED gates.
• Validate before persisting to {{OUTPUT_DIR}}/.
• Story-driven dev. No code without a story file. Use aped-story first.
• Frontend = visual verification. Use mcp__react-grab-mcp__get_element_context at every GREEN.

State

• Engine: {{APED_DIR}}/ (immutable) · Artifacts: {{OUTPUT_DIR}}/ (evolves)
• State: {{OUTPUT_DIR}}/state.yaml · Lessons: {{OUTPUT_DIR}}/lessons.md
• Project: {{project_name}} ({{user_name}}, {{communication_language}})

Lessons File

Also ensure {{OUTPUT_DIR}}/lessons.md exists. If missing, create it with the template:

# Lessons Learned

Patterns from user corrections — so the same mistake isn't made twice.

## Format
- **Date:** YYYY-MM-DD
- **Mistake:** What I did wrong
- **Correction:** What the user told me
- **Rule:** The pattern to apply going forward

## Entries

<!-- Add new entries at the top -->

Discussion with User

Before writing, present a summary:

• "Will create CLAUDE.md from scratch" (Case A)
• "Will update existing APED block (lines X-Y)" (Case B)
• "Will inject APED block at the {location}" (Case C)

⏸ GATE: User confirms before any write.

Output

1. Write/update CLAUDE.md with the APED block in markers
2. Ensure {{OUTPUT_DIR}}/lessons.md exists
3. Report what changed (lines added/updated)

Common Issues

• CLAUDE.md has conflicting rules: Discuss with user — APED rules vs existing rules. User decides which wins.
• CLAUDE.md is huge (>500 lines): Show only the diff, not the full file. Confirm before write.
• User wants to remove APED block: Just delete the markers and content between them. The skill won't re-add unless explicitly invoked.

Next Step

Tell the user: "CLAUDE.md updated. APED block is now at lines X-Y. Re-run aped-claude anytime to refresh after APED updates."