agentic-sdlc-kit CLAUDE.md

CLAUDE.md

Working notes for agents editing this repository. Not user documentation — that's README.md, and it must be updated whenever the facts here change.

1. What you are working on

This repo contains twelve Agent Skills (open SKILL.md standard) that form one SDLC pipeline. There is no application code, build system, test suite, or linter. The deliverable is instruction content loaded into an agent's context at runtime.

Consequences for how you work here:

• "Correctness" means the instructions are unambiguous, well-scoped, and trigger reliably — not that something compiles. You cannot run these skills to test them; review by reading.
• Every token costs. SKILL.md is loaded on every invocation. Prefer deleting a sentence to adding one. Depth goes in references/, read on demand.
• The twelve skills are coupled. Changing what one emits ripples into how the next ingests it. §4 lists the couplings; check them before editing any skill.
• Never write project-specific lessons back into a skill folder. Skills emit project-owned artifacts (scaffold-notes.md, deployment-notes.md, …); that's where run-specific knowledge lives.

2. Layout and install-path invariants

skills/<skill-name>/
├── SKILL.md            # required: frontmatter + the workflow
└── references/         # optional: guides SKILL.md tells the agent to read on demand

Load-bearing and easy to break:

• skills/<name>/SKILL.md is the flat layout the skills CLI discovers. Moving a skill out of skills/ breaks npx skills add <repo> --skill <name>.
• Frontmatter has exactly two keys: name and description. name must equal the directory name and the --skill argument. No license: key, no per-file headers — SKILL.md content enters an agent's context on every invocation.
• description is the only thing an agent sees when deciding to invoke the skill. It carries the trigger phrases and the "use this when…" intent. Editing it changes when the skill fires — treat as load-bearing, never boilerplate.
• The CLI resolves against the pushed GitHub repo (zeeshanhanif/agentic-sdlc-kit), not the local tree. Layout/frontmatter changes reach users only after a push.
• Manual install lands at ~/.claude/skills/<name>/SKILL.md (personal) or .claude/skills/<name>/SKILL.md (project). One level too deep silently fails.
• Renaming a skill directory or its frontmatter name changes the install command → update README's Install section and every example in lockstep.