
agent-alchemy-dev-tools
Agent Alchemy Dev Tools — dev utilities, debugging, and workflow enhancements
- version
- 0.3.4
- GitHub stars
- 45
Install
/plugin install agent-alchemy-dev-tools@agent-alchemyRun it inside Claude Code after adding the marketplace with /plugin marketplace add sequenzia/agent-alchemy.
Contents
Discovered from sourceSkills 9
Architecture Patterns
This skill provides knowledge about common architectural patterns to help design feature implementations. Apply these patterns based on the project's existing architecture and the feature's requirements.
Diagram Convention
Architecture visualizations use Mermaid syntax with classDef styling (color:#000 for text readability). When creating architecture visualizations based on these patterns, follow the technical-diagrams skill conventions.
Pattern Selection Guide
Choose patterns based on:
- Existing architecture - Match what's already in use
- Team familiarity - Use patterns the team knows
- Feature requirements - Some patterns fit better for certain features
- Scale requirements - Consider current and future scale
Layered Architecture (N-Tier)
When to use: Most web applications, CRUD operations, clear separation of concerns needed
Layers:
flowchart TD
A["Presentation Layer — UI, API endpoints, controllers"]:::primary
B["Application Layer — Use cases, orchestration, DTOs"]:::secondary
C["Domain Layer — Business logic, entities, rules"]:::success
D["Infrastructure Layer — Database, external services, I/O"]:::neutral
A --> B --> C --> D
classDef primary fill:#dbeafe,stroke:#2563eb,color:#000
classDef secondary fill:#f3e8ff,stroke:#7c3aed,color:#000
classDef success fill:#dcfce7,stroke:#16a34a,color:#000
classDef neutral fill:#f3f4f6,stroke:#6b7280,color:#000
Key rules:
- Dependencies flow downward only
- Each layer only talks to the layer directly below
- Domain layer has no external dependencies
Implementation tips:
- Use interfaces at layer boundaries
- Keep domain logic in the domain layer, not controllers
- Use DTOs to transfer data between layers
MVC (Model-View-Controller)
When to use: Web applications with server-rendered views, simple CRUD apps
Components:
flowchart LR
U1[User]:::neutral -->|input| CT[Controller]:::primary
CT -->|updates| M[Model]:::secondary
M -->|reads| CT
CT -->|renders| V[View]:::success
V -->|response| U2[User]:::neutral
classDef primary fill:#dbeafe,stroke:#2563eb,color:#000
classDef secondary fill:#f3e8ff,stroke:#7c3aed,color:#000
classDef success fill:#dcfce7,stroke:#16a34a,color:#000
classDef neutral fill:#f3f4f6,stroke:#6b7280,color:#000
Model: Data and business logic View: Presentation/UI Controller: Handles input, coordinates model and view
Implementation tips:
- Keep controllers thin - delegate to services
- Models should be framework-agnostic when possible
- Views should have minimal logic
Repository Pattern
When to use: Data access abstraction, testability, multiple data sources
Structure:
interface UserRepository {
findById(id: string): Promise<User | null>;
findByEmail(email: string): Promise<User | null>;
save(user: User): Promise<User>;
delete(id: string): Promise<void>;
}
class PostgresUserRepository implements UserRepository {
// Implementation using PostgreSQL
}
class InMemoryUserRepository implements UserRepository {
// Implementation for testing
}
Benefits:
- Abstracts data access details
- Easy to swap implementations
- Simplifies testing with in-memory implementations
Service Layer Pattern
When to use: Complex business logic, multiple entry points (API, CLI, queue)
Structure:
class UserService {
constructor(
private userRepo: UserRepository,
private emailService: EmailService,
private logger: Logger
) {}
async registerUser(data: RegisterDTO): Promise<User> {
// Validation
// Business logic
// Coordination of multiple repositories/services
// Return result
}
}
Implementation tips:
- Services contain business logic, not controllers
- One service per domain concept
- Services can call other services (but avoid cycles)
Event-Driven Architecture
When to use: Decoupled components, async processing, audit trails, notifications
Patterns:
Event Emitter (Simple)
// Emit events for side effects
userService.on('userCreated', async (user) => {
await emailService.sendWelcome(user);
await analyticsService.trackSignup(user);
});
Message Queue (Distributed)
flowchart LR
P[Producer]:::primary --> Q[Queue]:::warning
Q --> C1[Consumer 1]:::secondary
Q --> C2[Consumer 2]:::secondary
classDef primary fill:#dbeafe,stroke:#2563eb,color:#000
classDef secondary fill:#f3e8ff,stroke:#7c3aed,color:#000
classDef warning fill:#fef3c7,stroke:#d97706,color:#000
Event structure:
interface DomainEvent {
type: string;
timestamp: Date;
payload: unknown;
metadata: {
correlationId: string;
causationId: string;
};
}
Implementation tips:
- Events should be immutable
- Include enough context to process without additional queries
- Handle idempotency for at-least-once delivery
CQRS (Command Query Responsibility Segregation)
When to use: Complex domains, different read/write patterns, high-performance reads needed
Structure:
flowchart TD
subgraph write["Commands (Write)"]
CMD[Command]:::primary --> CH[Command Handler]:::secondary
CH --> WM[Write Model]:::secondary
WM --> WDB[Write Database]:::neutral
end
subgraph read["Queries (Read)"]
QRY[Query]:::primary --> QH[Query Handler]:::secondary
QH --> RM[Read Model]:::secondary
RM --> RDB[Read Database]:::neutral
end
classDef primary fill:#dbeafe,stroke:#2563eb,color:#000
classDef secondary fill:#f3e8ff,stroke:#7c3aed,color:#000
classDef neutral fill:#f3f4f6,stroke:#6b7280,color:#000
style write fill:#f8fafc,stroke:#94a3b8,color:#000
style read fill:#f8fafc,stroke:#94a3b8,color:#000
Simplified CQRS:
// Commands modify state
class CreateUserCommand {
execute(data: CreateUserDTO): Promise<void>
}
// Queries return data without modification
class GetUserQuery {
execute(id: string): Promise<UserDTO>
}
Implementation tips:
- Start simple - same database, different models
- Use for complex domains where read/write models differ
- Consider eventual consistency implications
Ports and Adapters (Hexagonal)
When to use: High testability needs, multiple I/O channels, long-lived applications
Structure:
flowchart TD
subgraph driving["Driving Adapters"]
H[HTTP]:::primary
CL[CLI]:::primary
Q[Queue]:::primary
T[Timer]:::primary
end
subgraph core["Application Core"]
subgraph domain["Domain Logic"]
DL[Business Rules]:::success
end
end
subgraph driven["Driven Adapters"]
DB[Database]:::neutral
CA[Cache]:::neutral
EM[Email]:::neutral
API[External API]:::neutral
end
H -->|port| DL
CL -->|port| DL
Q -->|port| DL
T -->|port| DL
DL -->|port| DB
DL -->|port| CA
DL -->|port| EM
DL -->|port| API
classDef primary fill:#dbeafe,stroke:#2563eb,color:#000
classDef success fill:#dcfce7,stroke:#16a34a,color:#000
classDef neutral fill:#f3f4f6,stroke:#6b7280,color:#000
style driving fill:#f8fafc,stroke:#94a3b8,color:#000
style core fill:#fefce8,stroke:#ca8a04,color:#000
style domain fill:#dcfce7,stroke:#16a34a,color:#000
style driven fill:#f8fafc,stroke:#94a3b8,color:#000
Key concept: Business logic at center, all I/O through ports/adapters
Implementation tips:
- Define ports (interfaces) for all external interactions
- Adapters implement ports for specific technologies
- Domain code never imports adapter code
Microservices Patterns
When to use: Large teams, independent deployability, different scaling needs
API Gateway
Single entry point that routes to services
Service Discovery
Services register themselves, clients look them up
Circuit Breaker
Prevent cascade failures when services are down
const breaker = new CircuitBreaker(remoteService.call, {
timeout: 3000,
errorThreshold: 50,
resetTimeout: 30000
});
Saga Pattern
Coordinate transactions across services
flowchart LR
SA[Service A]:::primary -->|step 1| SB[Service B]:::primary -->|step 2| SC[Service C]:::primary
SC -.->|failure| CC[Compensate C]:::danger
CC -.-> CB[Compensate B]:::danger
CB -.-> CA[Compensate A]:::danger
classDef primary fill:#dbeafe,stroke:#2563eb,color:#000
classDef danger fill:#fee2e2,stroke:#dc2626,color:#000
Choosing the Right Pattern
| Scenario | Recommended Pattern |
|---|---|
| Simple CRUD app | MVC + Repository |
| Complex business logic | Layered + Service Layer |
| Need audit trail | Event-Driven |
| High read/write disparity | CQRS |
| Maximum testability | Hexagonal |
| Multiple teams/services | Microservices patterns |
Anti-Patterns to Avoid
- Big Ball of Mud - No clear structure
- God Object - One class does everything
- Spaghetti Code - Tangled dependencies
- Golden Hammer - Using one pattern for everything
- Premature Optimization - Complex patterns for simple needs
Application Guidelines
- Match existing architecture - Don't introduce new patterns unnecessarily
- Start simple - Add complexity only when needed
- Document decisions - Explain why a pattern was chosen
- Consider team skills - A simpler pattern well-executed beats a complex one poorly understood
Bug Killer — Hypothesis-Driven Debugging Workflow
Execute a systematic debugging workflow that enforces investigation before fixes. Every bug gets a hypothesis journal, evidence gathering, and root cause confirmation before any code changes.
CRITICAL: Complete ALL 5 phases. The workflow is not complete until Phase 5: Wrap-up & Report is finished. After completing each phase, immediately proceed to the next phase without waiting for user prompts.
Phase Overview
- Triage & Reproduction — Understand, reproduce, route to quick or deep track
- Investigation — Gather evidence with language-specific techniques
- Root Cause Analysis — Confirm root cause through hypothesis testing
- Fix & Verify — Fix with proof, regression test, quality check
- Wrap-up & Report — Document trail, capture learnings
Phase 1: Triage & Reproduction
Goal: Understand the bug, reproduce it, and decide the investigation track.
1.1 Parse Context
Extract from $ARGUMENTS and conversation context:
- Bug description: What's failing? Error messages, symptoms
- Reproduction steps: How to trigger the bug (test command, user action, etc.)
- Environment: Language, framework, test runner, relevant config
- Prior attempts: Has the user already tried fixes? What didn't work?
- Deep flag: If
--deepis present, skip triage and go directly to deep track (jump to Phase 2 deep track)
1.2 Reproduce the Bug
Attempt to reproduce before investigating:
- If a failing test was mentioned, run it:
# Run the specific test to confirm the failure <test-runner> <test-file>::<test-name> - If an error was described, find and trigger it
- If neither, search for related test files and run them
Capture the exact error output — this is your primary evidence.
If the bug cannot be reproduced:
- Ask the user for more context via AskUserQuestion
- Check if it's environment-specific or intermittent
- Note "not yet reproduced" in the hypothesis journal
1.3 Form Initial Hypothesis
Based on the error message and context, form your first hypothesis:
### H1: [Title]
- Hypothesis: [What you think is causing the bug]
- Evidence for: [What supports this — error message, stack trace, etc.]
- Evidence against: [Anything that contradicts it — if none yet, say "None yet"]
- Test plan: [Specific steps to confirm or reject]
- Status: Pending
1.4 Route to Track
Quick-fix signals (ALL must be true):
- Clear, specific error message pointing to exact location
- Localized to 1-2 files (not spread across the codebase)
- Obvious fix visible from reading the error location
- No concurrency, timing, or state management involved
Deep-track signals (ANY one triggers deep track):
- Bug spans 3+ files or modules
- Root cause unclear from the error message alone
- Intermittent or environment-dependent failure
- Involves concurrency, timing, shared state, or async behavior
- User already tried fixes that didn't work
- Generic error message (e.g., "null reference" without clear origin)
- Stack trace points to library/framework code rather than application code
Present your assessment via AskUserQuestion:
- Summarize the bug and your initial hypothesis
- Recommend quick or deep track with justification
- Options: "Quick track (Recommended)" / "Deep track" / "Deep track" / "Quick track" — depending on your assessment
- Let the user override your recommendation
Track escalation rule: If during quick track execution, 2 hypotheses are rejected, automatically escalate to deep track. Preserve all hypothesis journal entries when escalating.
Phase 2: Investigation
Goal: Gather evidence systematically, guided by language-specific techniques.
2.1 Load Language Reference
Detect the primary language of the bug's context and load the appropriate reference:
| Language | Reference File |
|---|---|
| Python | Read ${CLAUDE_PLUGIN_ROOT}/skills/bug-killer/references/python-debugging.md |
| TypeScript / JavaScript | Read ${CLAUDE_PLUGIN_ROOT}/skills/bug-killer/references/typescript-debugging.md |
| Other / Multiple | Read ${CLAUDE_PLUGIN_ROOT}/skills/bug-killer/references/general-debugging.md |
Always also load general-debugging.md as a supplement when using a language-specific reference.
2.2 Quick Track Investigation
For quick-track bugs, investigate directly:
- Read the error location — the file and function where the error occurs
- Read the immediate callers — 1-2 files up the call chain
- Check recent changes —
git log --oneline -5 -- <file>for the affected files - Update hypothesis — does the evidence support H1? Add evidence for/against
Proceed to Phase 3 (quick track).
2.3 Deep Track Investigation
For deep-track bugs, use parallel exploration agents:
-
Plan exploration areas — identify 2-3 focus areas based on the bug:
- Focus 1: The error site and immediate code path
- Focus 2: Data flow and state management leading to the error
- Focus 3: Related subsystems, configuration, or external dependencies
-
Launch code-explorer agents:
Spawn 2-3 code-explorer agents from core-tools:
Use Task tool with subagent_type: "agent-alchemy-core-tools:code-explorer" Prompt for each agent: Bug context: [description of the bug and error] Focus area: [specific area for this agent] Investigate this focus area in relation to the bug: - Find all relevant files - Trace the execution/data path - Identify where behavior diverges from expected - Note any suspicious patterns, recent changes, or known issues - Report structured findingsLaunch agents in parallel for independent focus areas.
-
Synthesize exploration results:
- Collect findings from all agents
- Identify convergence (multiple agents pointing to same area)
- Update hypothesis journal with new evidence
- Form additional hypotheses if evidence warrants (aim for 2-3 total)
Proceed to Phase 3 (deep track).
Phase 3: Root Cause Analysis
Goal: Confirm the root cause through systematic hypothesis testing.
3.1 Quick Track Root Cause
For quick-track bugs:
-
Verify the hypothesis:
- Read the specific code identified in Phase 2
- Trace the logic step-by-step
- Confirm that the hypothesized cause produces the observed error
-
If confirmed (Status → Confirmed):
- Update H1 with confirming evidence
- Proceed to Phase 4
-
If rejected (Status → Rejected):
- Update H1 with evidence against and reason for rejection
- Form a new hypothesis (H2) based on what you learned
- Investigate H2 following Phase 2 quick track steps
- If H2 is also rejected → escalate to deep track
- Preserve all journal entries, continue with Phase 2 deep track
3.2 Deep Track Root Cause
For deep-track bugs:
-
Prepare hypotheses for testing:
- You should have 2-3 hypotheses from Phase 2
- Each needs a concrete test plan (how to confirm or reject)
-
Launch bug-investigator agents:
Spawn 1-3 bug-investigator agents to test hypotheses in parallel:
Use Task tool with subagent_type: "bug-investigator" Prompt for each agent: Bug context: [description of the bug and error] Hypothesis to test: [specific hypothesis] Test plan: 1. [Step 1 — e.g., run this specific test with these arguments] 2. [Step 2 — e.g., check git blame for this function] 3. [Step 3 — e.g., trace the data from input to error site] Report your findings with verdict (confirmed/rejected/inconclusive), evidence, and recommendations.Launch agents in parallel when they test independent hypotheses.
-
Evaluate results:
-
Update hypothesis journal with each agent's findings
-
If one hypothesis is confirmed → proceed to Phase 4
-
If all are rejected/inconclusive → apply 5 Whys technique:
Take the strongest "inconclusive" finding and ask "why?" iteratively:
Observed: [what actually happens] Why? → [first-level cause] Why? → [second-level cause] Why? → [root cause] -
Form new hypotheses from 5 Whys analysis and repeat investigation
-
-
If stuck after 2 rounds of investigation:
- Present all findings to the user via AskUserQuestion
- Share the hypothesis journal
- Ask for additional context or direction
- Options: "Continue investigating", "Try a different angle", "Provide more context"
Phase 4: Fix & Verify
Goal: Fix the root cause and prove the fix works.
4.1 Design the Fix
Before writing any code:
- Explain the root cause — state clearly what's wrong and why
- Explain the fix — describe what will change and WHY it addresses the root cause
- Identify affected files — list every file that needs modification
- Consider side effects — could this fix break other behavior?
4.2 Implement the Fix
- Read all files that will be modified before making changes
- Apply the fix using Edit tool — minimal, focused changes
- Match existing patterns — follow the codebase's conventions
4.3 Run Tests
-
Run the originally failing test — it should now pass:
<test-runner> <test-file>::<test-name> -
Run related tests — tests in the same file and nearby test files:
<test-runner> <test-directory> -
If tests fail:
- Determine if the failure is related to the fix or pre-existing
- If related, revise the fix (do NOT revert to a different approach without updating the hypothesis journal)
- If pre-existing, note it but don't let it block the fix
4.4 Write Regression Test
Write a test that would have caught this bug:
- The test should fail WITHOUT the fix (verifying it tests the right thing)
- The test should pass WITH the fix
- The test should be minimal — test the specific behavior that was broken
- Place it in the appropriate test file following project conventions
4.5 Deep Track: Quality Check and Related Issues
Deep track only — skip on quick track.
-
Load code-quality skill:
Read ${CLAUDE_PLUGIN_ROOT}/skills/code-quality/SKILL.mdReview the fix against code quality principles.
-
Check for related issues:
- Search for the same pattern elsewhere in the codebase:
Grep for the pattern that caused the bug - If the same bug exists in other locations, report them to the user
- Ask via AskUserQuestion: "Fix all related instances now?" / "Fix only the reported bug" / "Create tasks for related fixes"
- Search for the same pattern elsewhere in the codebase:
Phase 5: Wrap-up & Report
Goal: Document the investigation trail and capture learnings.
5.1 Bug Fix Summary
Present to the user:
## Bug Fix Summary
### Bug
[One-line description of the bug]
### Root Cause
[What was actually wrong and why]
### Fix Applied
[What was changed, with file:line references]
### Tests
- [Originally failing test]: Now passing
- [Regression test added]: [test name and location]
- [Related tests]: All passing
### Track
[Quick / Deep] [Escalated from quick: Yes/No]
5.2 Hypothesis Journal Recap
Present the complete hypothesis journal showing the investigation trail:
### Investigation Trail
#### H1: [Title]
- Status: Confirmed / Rejected
- [Key evidence summary]
#### H2: [Title] (if applicable)
- Status: Confirmed / Rejected
- [Key evidence summary]
[... additional hypotheses ...]
5.3 Project Learnings
Load the project-learnings skill to evaluate whether this bug reveals project-specific knowledge worth capturing:
Read ${CLAUDE_PLUGIN_ROOT}/skills/project-learnings/SKILL.md
Follow its workflow to evaluate the finding. Common debugging discoveries that qualify:
- Surprising API behavior specific to this project
- Undocumented conventions that caused the bug
- Architectural constraints that aren't obvious from the code
5.4 Deep Track: Future Recommendations
Deep track only:
If the investigation revealed broader concerns, present recommendations:
- Architecture improvements to prevent similar bugs
- Missing test coverage areas
- Documentation gaps
- Monitoring or alerting suggestions
5.5 Next Steps
Offer the user options via AskUserQuestion:
- "Commit the fix" — proceed to commit workflow
- "Review the changes" — show a diff of all modifications
- "Run full test suite" — run the complete test suite to verify no regressions
- "Done" — wrap up the session
Hypothesis Journal
The hypothesis journal is the core artifact of this workflow. Maintain it throughout all phases.
Format
## Hypothesis Journal — [Bug Title]
### H1: [Descriptive Title]
- **Hypothesis:** [What's causing the bug — be specific]
- **Evidence for:** [Supporting observations with file:line references]
- **Evidence against:** [Contradicting observations]
- **Test plan:** [Concrete steps to confirm or reject]
- **Status:** Pending / Confirmed / Rejected
- **Notes:** [Additional context, timestamps, agent findings]
### H2: [Descriptive Title]
[Same format]
Rules
- Minimum hypotheses: 1 on quick track, 2-3 on deep track
- Never delete entries — rejected hypotheses are valuable context
- Update incrementally — add evidence as you find it, don't wait
- Be specific — "the data is wrong" is not a hypothesis; "processOrder receives dollars but expects cents" is
Track Reference
| Aspect | Quick Track | Deep Track |
|---|---|---|
| Investigation | Read error location + 1-2 callers | 2-3 code-explorer agents in parallel |
| Hypotheses | Minimum 1 | Minimum 2-3 |
| Root cause testing | Manual verification | 1-3 bug-investigator agents in parallel |
| Fix validation | Run failing + related tests | Tests + code-quality skill + related issue scan |
| Auto-escalation | After 2 rejected hypotheses | N/A |
| Typical complexity | Off-by-one, typo, wrong argument, missing null check | Race condition, state corruption, multi-file logic error |
Agent Coordination
Code Explorers (Phase 2, deep track)
Use cross-plugin agent reference:
subagent_type: "agent-alchemy-core-tools:code-explorer"
These are Sonnet-model read-only agents that explore codebase areas. Give each a distinct focus area related to the bug. They report structured findings.
Bug Investigators (Phase 3, deep track)
Use same-plugin agent reference:
subagent_type: "bug-investigator"
These are Sonnet-model agents with Bash access for running tests and git commands, but no Write/Edit — they investigate and report evidence, they don't fix code. Give each a specific hypothesis to test.
Error Handling
- If an agent fails, continue with remaining agents' results
- If all agents fail in a phase, fall back to manual investigation
- Never block on a single agent — partial results are better than no results
Error Recovery
If any phase fails:
- Explain what went wrong and what you've learned so far
- Present the hypothesis journal as-is
- Ask the user how to proceed via AskUserQuestion:
- "Retry this phase"
- "Skip to fix" (if you have enough evidence)
- "Provide more context"
- "Abort"
Keep a Changelog Format
This skill provides guidelines for writing and formatting changelogs following the Keep a Changelog specification.
Core Principles
- Changelogs are for humans - Write for users, not machines
- Every version gets a section - Including
[Unreleased]for upcoming changes - Changes are grouped by type - Consistent categorization
- Versions are linkable - Each version header links to comparison
- Latest version comes first - Reverse chronological order
- Release dates are shown - ISO format: YYYY-MM-DD
Change Categories
Use these categories in this order:
| Category | Description | When to Use |
|---|---|---|
| Added | New features | New functionality users can now do |
| Changed | Changes in existing functionality | Behavior modifications, improvements |
| Deprecated | Soon-to-be removed features | Features marked for future removal |
| Removed | Removed features | Features that no longer exist |
| Fixed | Bug fixes | Corrections to existing functionality |
| Security | Security vulnerability fixes | Security-related changes |
Category Guidelines
Added
- New user-facing features
- New API endpoints
- New configuration options
- New integrations
Changed
- Performance improvements
- UX/UI changes
- Default value changes
- Behavior modifications
Deprecated
- Features planned for removal
- APIs being replaced
- Include migration path when possible
Removed
- Breaking changes (removed functionality)
- Deleted APIs or features
- Always note what replaced it (if applicable)
Fixed
- Bug corrections
- Error handling improvements
- Edge case fixes
Security
- Vulnerability patches
- Security-related fixes
- Always include CVE if available
Entry Writing Guidelines
Use Imperative Mood
Start entries with imperative verbs:
| Do | Don't |
|---|---|
| Add support for... | Added support for... |
| Fix crash when... | Fixed a crash that occurred when... |
| Remove deprecated... | Removed the deprecated... |
| Change default to... | Changed the default to... |
Focus on User Impact
Write from the user's perspective:
| Good (User-focused) | Bad (Implementation-focused) |
|---|---|
| Add dark mode toggle | Implement ThemeProvider context |
| Fix login failing silently | Add try-catch to auth handler |
| Speed up page load by 40% | Optimize database queries |
Be Specific and Concise
| Good (Specific) | Bad (Vague) |
|---|---|
| Fix crash when uploading files over 10MB | Fix upload bug |
| Add CSV export for transaction history | Add export feature |
| Change session timeout from 30 to 60 minutes | Update session settings |
Include Context When Helpful
Use parenthetical context for clarity:
- Add OAuth2 support (Google, GitHub)
- Fix timezone handling (UTC offset calculation)
- Change rate limit (100 → 500 requests/minute)
Changelog Structure
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/),
and this project adheres to [Semantic Versioning](https://semver.org/).
## [Unreleased]
### Added
- New entries go here
## [1.0.0] - 2024-01-15
### Added
- Initial public release
- Feature A with description
- Feature B with description
### Changed
- Improvement to existing feature
### Fixed
- Bug fix description
## [0.9.0] - 2024-01-01
### Added
- Beta release features
[Unreleased]: https://github.com/owner/repo/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/owner/repo/compare/v0.9.0...v1.0.0
[0.9.0]: https://github.com/owner/repo/releases/tag/v0.9.0
Semantic Versioning Connection
Changelog categories map to version bumps:
| Category | Version Impact |
|---|---|
| Removed (after v1.0) | MAJOR bump |
| Removed (before v1.0) | MINOR bump |
| Added, Changed | MINOR bump |
| Deprecated, Fixed, Security | PATCH bump |
What NOT to Include
- Internal refactoring (unless it affects users)
- Dependency updates (unless they affect functionality)
- Test changes
- CI/CD changes
- Documentation-only changes (unless user-facing docs)
- Code style/formatting changes
Reference Files
references/entry-examples.md- Examples of well-written vs poorly-written entries
Code Quality
This skill provides code quality principles and best practices for reviewing and improving implementations.
SOLID Principles
Single Responsibility Principle (SRP)
A class/function should have one reason to change.
Bad:
class UserService {
createUser(data) { /* creates user */ }
sendEmail(user) { /* sends email */ }
generateReport(users) { /* generates report */ }
}
Good:
class UserService {
createUser(data) { /* creates user */ }
}
class EmailService {
sendEmail(user) { /* sends email */ }
}
class ReportService {
generateReport(users) { /* generates report */ }
}
Open/Closed Principle (OCP)
Open for extension, closed for modification.
Bad: Adding new payment types requires modifying existing code
function processPayment(type, amount) {
if (type === 'credit') { /* ... */ }
else if (type === 'debit') { /* ... */ }
// Must modify to add new types
}
Good: New payment types can be added without modification
interface PaymentProcessor {
process(amount: number): Promise<void>;
}
class CreditProcessor implements PaymentProcessor { /* ... */ }
class DebitProcessor implements PaymentProcessor { /* ... */ }
Liskov Substitution Principle (LSP)
Subtypes must be substitutable for their base types.
Bad:
class Bird {
fly() { /* ... */ }
}
class Penguin extends Bird {
fly() { throw new Error("Can't fly!"); } // Violates LSP
}
Good:
class Bird { /* ... */ }
class FlyingBird extends Bird {
fly() { /* ... */ }
}
class Penguin extends Bird { /* no fly method */ }
Interface Segregation Principle (ISP)
Clients shouldn't depend on interfaces they don't use.
Bad:
interface Worker {
work(): void;
eat(): void;
sleep(): void;
}
Good:
interface Workable { work(): void; }
interface Eatable { eat(): void; }
interface Sleepable { sleep(): void; }
Dependency Inversion Principle (DIP)
Depend on abstractions, not concretions.
Bad:
class UserService {
private db = new PostgresDatabase();
}
Good:
class UserService {
constructor(private db: Database) {}
}
DRY, KISS, YAGNI
DRY (Don't Repeat Yourself)
Every piece of knowledge should have a single representation.
Apply when:
- Same logic appears 3+ times
- Changes to one place require changes to others
- Bug fixes need to be applied in multiple places
Don't over-apply:
- Two similar things might diverge later
- Premature abstraction can be worse than duplication
KISS (Keep It Simple, Stupid)
Prefer simple solutions over clever ones.
Simple code:
- Easy to read and understand
- Easy to debug
- Easy to modify
- Has fewer bugs
YAGNI (You Aren't Gonna Need It)
Don't add functionality until it's needed.
Avoid:
- Building for hypothetical requirements
- Adding "just in case" features
- Over-engineering for scale you don't have
Clean Code Principles
Meaningful Names
// Bad
const d = new Date();
const arr = users.filter(u => u.a > 18);
// Good
const currentDate = new Date();
const adultUsers = users.filter(user => user.age > 18);
Small Functions
- Do one thing well
- Few parameters (ideally 0-3)
- Single level of abstraction
Avoid Side Effects
// Bad: side effect hidden in getter
getUser() {
this.lastAccess = Date.now(); // Side effect!
return this.user;
}
// Good: explicit about what it does
getUser() {
return this.user;
}
recordAccess() {
this.lastAccess = Date.now();
}
Error Handling
// Be specific about errors
class ValidationError extends Error {}
class NotFoundError extends Error {}
class AuthorizationError extends Error {}
// Handle at appropriate level
try {
await processOrder(order);
} catch (error) {
if (error instanceof ValidationError) {
return res.status(400).json({ error: error.message });
}
if (error instanceof NotFoundError) {
return res.status(404).json({ error: error.message });
}
throw error; // Re-throw unexpected errors
}
Testing Strategies
Test Pyramid
/\
/ \ E2E Tests (few)
/────\
/ \ Integration Tests (some)
/────────\
/ \ Unit Tests (many)
/────────────\
Unit Testing
- Test individual functions/classes
- Mock dependencies
- Fast and isolated
describe('calculateTotal', () => {
it('sums item prices', () => {
const items = [{ price: 10 }, { price: 20 }];
expect(calculateTotal(items)).toBe(30);
});
it('applies discount', () => {
const items = [{ price: 100 }];
expect(calculateTotal(items, { discount: 0.1 })).toBe(90);
});
it('handles empty cart', () => {
expect(calculateTotal([])).toBe(0);
});
});
Integration Testing
- Test component interactions
- Use real dependencies (or test doubles)
- Database, API integration
Test Behavior, Not Implementation
// Bad: tests implementation details
it('calls _internalMethod', () => {
const spy = jest.spyOn(service, '_internalMethod');
service.doThing();
expect(spy).toHaveBeenCalled();
});
// Good: tests behavior
it('sends welcome email on registration', async () => {
await service.registerUser({ email: 'test@test.com' });
expect(emailSent).toContainEqual({
to: 'test@test.com',
template: 'welcome'
});
});
Edge Cases to Test
- Empty inputs
- Null/undefined
- Boundary values
- Error conditions
- Concurrent operations
- Large inputs
Code Review Checklist
Correctness
- Does the code do what it's supposed to?
- Are edge cases handled?
- Are error conditions handled?
Security
- Is input validated?
- Are outputs escaped?
- Are secrets protected?
Performance
- Are there N+1 queries?
- Are there unnecessary loops?
- Is caching used appropriately?
Maintainability
- Is the code readable?
- Are names meaningful?
- Is complexity reasonable?
- Is there appropriate documentation?
Testing
- Are there tests?
- Do tests cover edge cases?
- Are tests maintainable?
Common Code Smells
| Smell | Description | Solution |
|---|---|---|
| Long Method | Function > 20-30 lines | Extract methods |
| Large Class | Class with too many responsibilities | Split into focused classes |
| Long Parameter List | > 3-4 parameters | Use parameter object |
| Duplicate Code | Same code in multiple places | Extract function |
| Dead Code | Unused code | Delete it |
| Magic Numbers | Unexplained numeric literals | Use named constants |
| Nested Conditionals | Deep if/else nesting | Early returns, extract methods |
| Feature Envy | Method uses another class's data heavily | Move method to that class |
Refactoring Techniques
Extract Function
When a code block can be grouped and named
Inline Function
When the function body is as clear as the name
Extract Variable
When an expression is complex
Rename Variable/Function
When the name doesn't communicate intent
Replace Conditional with Polymorphism
When you have repeated switch/if statements on type
Introduce Parameter Object
When several parameters travel together
Documentation Manager Workflow
Execute a structured 6-phase workflow for managing documentation. Supports two documentation formats (MkDocs sites and standalone markdown files) and three action types (generate, update, change summary).
CRITICAL: Complete ALL applicable phases. Some phases are conditional. After completing each phase, immediately proceed to the next phase without waiting for user prompts.
Phase Overview
Execute these phases in order, completing ALL of them:
- Interactive Discovery — Determine documentation type, format, and scope through user interaction
- Project Detection & Setup — Detect project context, conditionally scaffold MkDocs
- Codebase Analysis — Deep codebase exploration using the deep-analysis skill
- Documentation Planning — Translate analysis findings into a concrete plan for user approval
- Documentation Generation — Launch docs-writer agents to generate content
- Integration & Finalization — Write files, validate, present results
Phase 1: Interactive Discovery
Goal: Determine through user interaction what documentation to create and in what format.
Step 1 — Infer intent from $ARGUMENTS
Parse the user's input to pre-fill selections:
- Keywords like "README", "CONTRIBUTING", "ARCHITECTURE" → infer
basic-markdown - Keywords like "mkdocs", "docs site", "documentation site" → infer
mkdocs - Keywords like "changelog", "release notes", "what changed" → infer
change-summary
If the intent is clear, present a summary for quick confirmation before proceeding (skip to Step 4). If ambiguous, proceed to Step 2.
Step 2 — Q1: Documentation type
If the documentation type is ambiguous or needs confirmation, use AskUserQuestion:
What type of documentation would you like to create?
1. "MkDocs documentation site" — Full docs site with mkdocs.yml, Material theme
2. "Basic markdown files" — Standalone files like README.md, CONTRIBUTING.md, ARCHITECTURE.md
3. "Change summary" — Changelog, release notes, commit message
Store as DOC_TYPE = mkdocs | basic-markdown | change-summary.
Step 3 — Conditional follow-up questions
If DOC_TYPE = mkdocs:
Q2: AskUserQuestion — Existing project or new setup?
- "Existing MkDocs project" →
MKDOCS_MODE = existing - "New MkDocs setup" →
MKDOCS_MODE = new
Q3 (if existing): AskUserQuestion — What to do?
- "Generate new pages"
- "Update existing pages"
- "Both — generate and update"
Store as
ACTION.
Q3 (if new): AskUserQuestion — Scope?
- "Full documentation"
- "Getting started only (minimal init)"
- "Custom pages"
Store as
MKDOCS_SCOPE. If custom, useAskUserQuestionfor desired pages (free text).
If DOC_TYPE = basic-markdown:
Q2: AskUserQuestion (multiSelect) — Which files?
- "README.md"
- "CONTRIBUTING.md"
- "ARCHITECTURE.md"
- "API documentation"
Store as
MARKDOWN_FILES. If "Other" is selected, useAskUserQuestionfor custom file paths/descriptions.
If DOC_TYPE = change-summary:
Q2: AskUserQuestion — What range?
- "Since last tag"
- "Between two refs"
- "Recent changes" Follow up for specific range details (tag name, ref pair, etc.).
Step 4 — Confirm selections
Present a summary of all selections and use AskUserQuestion:
- "Proceed"
- "Change selections"
If the user wants to change, loop back to the relevant question.
Immediately proceed to Phase 2.
Phase 2: Project Detection & Setup
Goal: Detect project context automatically, conditionally scaffold MkDocs.
Step 1 — Detect project metadata (all paths)
- Check manifests:
package.json,pyproject.toml,Cargo.toml,go.mod,pom.xml - Run
git remote get-url origin 2>/dev/null - Note primary language and framework
Step 2 — Check existing documentation (all paths)
- Glob for
docs/**/*.md,README.md,CONTRIBUTING.md,ARCHITECTURE.md - For MkDocs: check for
mkdocs.yml/mkdocs.yaml, read if found
Step 3 — MkDocs Initialization (only if DOC_TYPE = mkdocs AND MKDOCS_MODE = new)
- Load
${CLAUDE_PLUGIN_ROOT}/skills/docs-manager/references/mkdocs-config-template.md - Fill template with detected metadata (ask via
AskUserQuestionif incomplete) - Ensure MkDocs dependencies are installed so the Phase 6 build/serve checks can run:
- Python project (
pyproject.toml): add adocsdependency group withmkdocs-materialandpymdown-extensions(e.g. under[dependency-groups]), then sync (uv sync --group docs, orpip install mkdocs-material). - Other projects: MkDocs is Python-based —
pip install mkdocs-material(orpipx). - If
mkdocsis already importable/on PATH, skip.
- Python project (
- Generate
mkdocs.yml(keep itsextra_csskey) and create:docs/index.mdanddocs/getting-started.mddocs/stylesheets/extra.css— the Mermaid dark-mode companion from the template. Not optional: the palette ships a darkslatescheme, and the standard Mermaid palette (light fills + dark text) is unreadable in dark mode without it.
- Present scaffold for confirmation before writing
If MKDOCS_SCOPE = minimal (getting started only): write the scaffold files (including docs/stylesheets/extra.css) and skip to Phase 6.
Step 4 — Set action-specific context (for update/change-summary)
For update modes, determine the approach:
- git-diff — Update docs affected by recent code changes (default if user mentions "recent changes" or a branch/tag)
- full-scan — Compare all source code against all docs for gap analysis (default if user says "full update" or "sync all")
- targeted — Update specific pages or sections (default if user specifies file paths or page names)
For change-summary, run git log and git diff --stat for the determined range.
Immediately proceed to Phase 3.
Phase 3: Codebase Analysis
Goal: Deep codebase exploration using the deep-analysis skill.
Skip conditions:
- Skip for
change-summary(uses git-based analysis instead — see below) - Skip for MkDocs minimal init-only (
MKDOCS_SCOPE = minimal)
Step 1 — Build documentation-focused analysis context
Construct a specific context string based on Phase 1 selections:
| Selection | Analysis Context |
|---|---|
| MkDocs generate | "Documentation generation — find all public APIs, architecture, integration points, and existing documentation..." |
| MkDocs update | "Documentation update — identify changes to public APIs, outdated references, documentation gaps..." |
| Basic markdown README | "Project overview — understand purpose, architecture, setup, key features, configuration, and dependencies..." |
| Basic markdown ARCHITECTURE | "Architecture documentation — map system structure, components, data flow, design decisions, key dependencies..." |
| Basic markdown API docs | "API documentation — find all public functions, classes, methods, types, their signatures and usage patterns..." |
| Basic markdown CONTRIBUTING | "Contribution guidelines — find dev workflow, testing setup, code style rules, commit conventions, CI process..." |
| Multiple files | Combine relevant contexts from above |
Step 2 — Run deep-analysis
Read ${CLAUDE_PLUGIN_ROOT}/../core-tools/skills/deep-analysis/SKILL.md and follow its workflow.
Pass the documentation-focused analysis context from Step 1.
Deep-analysis handles all agent orchestration (reconnaissance, team planning, approval — auto-approved when skill-invoked — team creation, code-explorers + code-synthesizer). Since docs-manager is the calling skill, deep-analysis returns control without standalone summary.
Note: Deep-analysis may return cached results if a valid exploration cache exists. In skill-invoked mode, cache hits are auto-accepted — this is expected behavior that avoids redundant exploration.
Step 3 — Supplemental analysis for update with git-diff mode
After deep-analysis, additionally:
- Run
git diff --name-only [base-ref]for changed files - Use Grep to search existing docs for references to changed files/functions
- Cross-reference with synthesis findings
For change-summary path (instead of deep-analysis)
- Run
git log --oneline [range]andgit diff --stat [range] - Launch 1 code-explorer agent using Task tool with
subagent_type: "code-explorer"to analyze the changed files:Analysis context: Change summary for [range] Focus area: These files changed in the specified range: [list from git diff --stat] For each significant change, identify: - What was added, modified, or removed - Impact on public APIs and user-facing behavior - Whether any changes are breaking Return a structured report of your findings.
Immediately proceed to Phase 4.
Phase 4: Documentation Planning
Goal: Translate analysis findings into a concrete documentation plan.
Step 1 — Produce plan based on doc type
MkDocs:
- Pages to create (with
docs/paths) - Pages to update (with specific sections)
- Proposed
mkdocs.ymlnav updates - Page dependency ordering (independent pages first, then pages that cross-reference them)
Basic Markdown:
- Files to create/update (with target paths)
- Proposed structure/outline for each file
- Content scope per file
Change Summary:
- Output formats to generate (Format 1: Changelog, Format 2: Commit message, Format 3: MkDocs page — only if MkDocs site exists)
- Range confirmation
- Scope of changes
Step 2 — User approval
Use AskUserQuestion:
- "Approve the plan as-is"
- "Modify the plan" (describe changes)
- "Reduce scope" (select specific items only)
Immediately proceed to Phase 5.
Phase 5: Documentation Generation
Goal: Generate content using docs-writer agents.
Step 1 — Load templates
- If
DOC_TYPE = change-summary: Read${CLAUDE_PLUGIN_ROOT}/skills/docs-manager/references/change-summary-templates.md - If
DOC_TYPE = basic-markdown: Read${CLAUDE_PLUGIN_ROOT}/skills/docs-manager/references/markdown-file-templates.md
Step 2 — Group by dependency
- Independent pages/files — Can be written without referencing other new content (API reference, standalone guides, individual markdown files)
- Dependent pages/files — Reference or summarize content from other pages (index pages, overview pages, README that links to CONTRIBUTING)
Step 3 — Launch docs-writer agents
Launch agents using Task tool with subagent_type: "docs-writer" and model: "opus".
Launch independent pages/files in parallel, then sequential for dependent ones (include generated content from independent pages in the prompt context).
MkDocs prompt template:
Documentation task: [page type — API reference / architecture / how-to / change summary]
Target file: [docs/path/to/page.md]
Output format: MkDocs
Project: [project name] at [project root]
MkDocs site context:
- Theme: Material for MkDocs
- Extensions available: admonitions, code highlighting, tabbed content, Mermaid diagrams
- Diagram guidance: The technical-diagrams skill is loaded — use Mermaid for all diagrams with its standard styling (light fills + dark text on nodes). The site ships a dark-mode companion stylesheet (`docs/stylesheets/extra.css`), so diagrams render correctly in both light and dark mode — keep the standard palette; do NOT hand-roll per-diagram dark-mode colors.
- Existing pages: [list of current doc pages]
Exploration findings:
[Relevant findings from Phase 3 for this page]
Existing page content (if updating):
[Current content of the page, or "New page — no existing content"]
Generate the complete page content in MkDocs-flavored Markdown.
Basic Markdown prompt template:
Documentation task: [file type — README / CONTRIBUTING / ARCHITECTURE / API docs]
Target file: [path/to/file.md]
Output format: Basic Markdown
Project: [project name] at [project root]
File type guidance:
[Relevant structural template from markdown-file-templates.md]
Exploration findings:
[Relevant findings from Phase 3 for this file]
Existing file content (if updating):
[Current content, or "New file — no existing content"]
Generate the complete file content in standard GitHub-flavored Markdown.
Do NOT use MkDocs-specific extensions (admonitions, tabbed content, code block titles).
Diagram guidance: The technical-diagrams skill is loaded — use Mermaid for all diagrams with its standard styling (light fills + dark text on nodes). GitHub renders Mermaid natively on a light canvas (standalone Markdown can't ship a dark-mode stylesheet, so the standard light-fill palette is the right choice here).
Step 4 — Review generated content
- Verify structure, check for unfilled placeholders
- Validate cross-references between pages/files use correct relative paths
Immediately proceed to Phase 6.
Phase 6: Integration & Finalization
Goal: Write files, validate, present results.
Step 1 — Write files
MkDocs:
- Write pages under
docs/ - Update
mkdocs.ymlnav — read current config, add new pages in logical positions, preserve existing structure
Basic Markdown:
- Write files to their target paths (project root or specified directories)
- For updates, use the Edit tool to modify existing files
Change Summary:
- Present outputs inline for review
- Write files as applicable (e.g., append to CHANGELOG.md)
Step 2 — Validate
MkDocs:
- Verify all files referenced in
navexist on disk using Glob - Check for broken cross-references between pages using Grep
- If
mkdocsCLI is available, runmkdocs build --strict 2>&1to check for warnings (non-blocking) - Confirm
docs/stylesheets/extra.cssexists andmkdocs.ymllists it underextra_css. - Verify dark mode — the check that catches hard-coded-color contrast regressions, and the one that would have prevented the Mermaid light-on-light bug. If the site has any Mermaid diagrams: run
mkdocs serve, open the site, toggle the palette to dark (slate), and confirm diagrams are legible in both modes — node/subgraph titles, edge labels, edges/arrows where they cross light fills, and sequence/ER text. Watch for the two classic failures: light-on-light text, and edges vanishing on light fills. If a diagram is unreadable in dark mode, the companion stylesheet is missing or mis-wired — see the technical-diagrams skill, "Styling and Theming → Dark-mode rendering".
Basic Markdown:
- Validate internal cross-references between files (e.g., README links to CONTRIBUTING)
- Check that referenced paths exist
Step 3 — Present results
Summarize what was done:
- Files created (with paths)
- Files updated (with description of changes)
- Navigation changes (if MkDocs)
- Any validation warnings
For change-summary, present generated outputs directly inline.
Step 4 — Next steps
Use AskUserQuestion with relevant options:
MkDocs:
- "Preview the site" (if
mkdocs serveis available) - "Commit the changes"
- "Generate additional pages"
- "Done — no further action"
Basic Markdown:
- "Commit the changes"
- "Generate additional files"
- "Review a specific file"
- "Done — no further action"
Error Handling
If any phase fails:
- Explain what went wrong
- Ask the user how to proceed:
- Retry the phase
- Skip to next phase (with partial results)
- Abort the workflow
Non-Git Projects
If the project is not a git repository:
- Skip git remote detection in Phase 2 (omit
repo_urlandrepo_namefrom mkdocs.yml) - The
updateaction with git-diff mode is unavailable — fall back to full-scan or targeted mode - The
change-summaryaction is unavailable — inform the user and suggest alternatives
Basic Markdown on Non-Git Projects
- CONTRIBUTING.md is still viable — use project conventions instead of git workflow sections
- Skip branch naming and PR process sections; focus on code style, testing, and setup
Phase Failure
- Explain the error clearly
- Offer retry/skip/abort options via
AskUserQuestion
Agent Coordination
- Phase 3: Exploration and synthesis handled by the deep-analysis skill, which uses Agent Teams with hub-and-spoke coordination. Deep-analysis performs reconnaissance, composes a team plan (auto-approved when invoked by another skill), assembles the team, and orchestrates its own code-explorer and code-synthesizer agents.
- Phase 5: docs-writer agents launched with
model: "opus"for high-quality content generation. Parallel for independent files, sequential for dependent files.
Additional Resources
- For MkDocs configuration template, see references/mkdocs-config-template.md
- For change summary formats, see references/change-summary-templates.md
- For standalone markdown file templates, see references/markdown-file-templates.md
Document Changes
Generate a structured markdown report documenting codebase changes from the current working session. The report captures files changed, commit history, and a human-readable summary suitable for team reviews, handoff documentation, or personal records.
Arguments
$ARGUMENTS— Optional scope or description for the report (e.g.,"auth refactor","add OAuth2 support"). Used to name the output file and populate the report's scope field. If not provided, scope is inferred from commit messages or changed file paths.
Workflow
Execute these 4 steps in order. Stop early if Step 1 or Step 2 determines there is nothing to report.
Step 1: Validate Git Repository
Verify the current directory is inside a git repository:
git rev-parse --is-inside-work-tree
- If the command fails or returns
false, stop and report: "Not inside a git repository. This skill requires git to gather change data." - If successful, continue to Step 2.
Step 2: Gather Changes and Metadata
Collect all change data by running these git commands. If any individual command fails, continue with the data that is available.
2.1 Repository Metadata
git branch --show-current
git config user.name
git remote get-url origin 2>/dev/null
date "+%Y-%m-%d %H:%M %Z"
2.2 Uncommitted Changes
git status --porcelain
git diff --stat
git diff --name-status
2.3 Staged Changes
git diff --cached --stat
git diff --cached --name-status
2.4 Recent Commits (up to 20)
git log --oneline -20
git log --format="%H|%s|%an|%ai" -20
2.5 Session Commit Diffs
If there are recent commits (N > 0 from Step 2.4):
git diff --stat HEAD~N..HEAD
git diff --name-status HEAD~N..HEAD
Replace N with the number of recent commits found (capped at 20). If the repo has fewer than N commits, use git diff --stat $(git rev-list --max-parents=0 HEAD)..HEAD instead.
2.6 Combine and Deduplicate
Build a unified list of all affected files from Steps 2.2–2.5, deduplicating entries. For each file, track:
- Status: Added (A), Modified (M), Deleted (D), Renamed (R)
- Source: Whether the change is committed, staged, unstaged, or untracked
Stop condition: If there are no uncommitted changes (Step 2.2 is empty), no staged changes (Step 2.3 is empty), and no recent commits (Step 2.4 is empty), stop and report: "No changes found in the current repository. Nothing to document."
Step 3: Determine Report Location
3.1 Generate Filename Description
Create a short kebab-case description (2-4 words) for the filename:
- If
$ARGUMENTSis provided: Convert to kebab-case (e.g.,"auth refactor"→auth-refactor) - If
$ARGUMENTSis not provided: Infer from the most common theme in commit messages or changed file paths (e.g.,api-bug-fixes,add-oauth2-support,ui-component-updates)
Build the recommended path: internal/reports/<description>-YYYY-MM-DD.md using today's date.
3.2 Ask User for Report Location
Use AskUserQuestion:
Where should the change report be saved?
Recommended: internal/reports/<description>-YYYY-MM-DD.md
Options:
- "Use recommended path (Recommended)" — Save to
internal/reports/<description>-YYYY-MM-DD.md - "Custom path" — User provides their own file path
If user selects "Custom path": Use a follow-up AskUserQuestion asking for the full file path.
3.3 Validate Path
- The path must end with
.md - If the parent directory does not exist, create it with
mkdir -p
Step 4: Generate and Write Report
Build the markdown report with the following structure, then write it using the Write tool.
Report Template
# Codebase Changes Report
## Metadata
| Field | Value |
|-------|-------|
| **Date** | YYYY-MM-DD |
| **Time** | HH:MM TZ |
| **Branch** | {current branch} |
| **Author** | {git user.name} |
| **Base Commit** | {earliest commit hash before session changes, or N/A} |
| **Latest Commit** | {most recent commit hash, or "uncommitted"} |
| **Repository** | {remote URL, or "local only"} |
**Scope**: {from $ARGUMENTS, or inferred from changes}
**Summary**: {1-2 sentence executive summary of what was done}
## Overview
{High-level stats paragraph}
- **Files affected**: N
- **Lines added**: +N
- **Lines removed**: -N
- **Commits**: N
## Files Changed
| File | Status | Lines | Description |
|------|--------|-------|-------------|
| `path/to/file.ts` | Modified | +12 / -3 | Brief description of changes |
| `path/to/new.ts` | Added | +45 | Brief description |
| `path/to/old.ts` | Deleted | -20 | Brief description |
## Change Details
### Added
- **`path/to/new.ts`** — Description of the new file and its purpose.
### Modified
- **`path/to/file.ts`** — What was changed and why (based on diff context).
### Deleted
- **`path/to/old.ts`** — Why it was removed or what replaced it.
## Git Status
### Staged Changes
{List of staged files from `git diff --cached --name-status`, or "No staged changes."}
### Unstaged Changes
{List of unstaged modifications from `git diff --name-status`, or "No unstaged changes."}
### Untracked Files
{List of untracked files from `git status --porcelain` (lines starting with `??`), or "No untracked files."}
## Session Commits
| Hash | Message | Author | Date |
|------|---------|--------|------|
| `abc1234` | feat: add login flow | Author Name | 2026-02-21 |
{Or "No commits in this session." if no recent commits}
Writing the Report
- If the parent directory does not exist, create it:
mkdir -p {parent_directory} - Use the
Writetool to create the report file at the chosen path. - If the write fails, report the error and use
AskUserQuestionto offer an alternative path.
Present Summary
After writing the report, present a brief summary of what was generated, then use AskUserQuestion:
Report written to {path}.
Summary: {1-2 sentence overview}
Files documented: N | Commits: N | Lines: +N / -N
What would you like to do next?
Options:
- "Review report" — Read the report back to the user using
Read - "Commit changes" — Suggest using
/git-committo commit outstanding changes - "Done" — End the workflow
Error Handling
| Scenario | Action |
|---|---|
| Not a git repo | Stop with clear message (Step 1) |
| No changes found | Stop with clear message (Step 2) |
| Individual git command fails | Continue with available data |
| Write fails | Offer alternative path via AskUserQuestion |
| Cannot determine scope | Use "session-changes" as the fallback description |
Section Guidelines
- Omit empty sections: If a section has no data (e.g., no deleted files, no untracked files), omit that section or subsection entirely rather than showing "None."
- File descriptions: Generate brief descriptions from diff context and file names. Keep each to one sentence.
- Commit hashes: Use short hashes (7 characters) in the report for readability.
- Line counts: Use
--statoutput to extract per-file line additions/deletions. If unavailable, omit the Lines column.
Feature Development Workflow
Execute a structured 7-phase feature development workflow. This workflow guides you through understanding, exploring, designing, implementing, and reviewing a feature.
CRITICAL: Complete ALL 7 phases. The workflow is not complete until Phase 7: Summary is finished. After completing each phase, immediately proceed to the next phase without waiting for user prompts.
Phase Overview
Execute these phases in order, completing ALL of them:
- Discovery - Understand the feature requirements
- Codebase Exploration - Map relevant code areas
- Clarifying Questions - Resolve ambiguities
- Architecture Design - Design the implementation approach
- Implementation - Build the feature
- Quality Review - Review for issues
- Summary - Document accomplishments
Phase 1: Discovery
Goal: Understand what the user wants to build.
-
Analyze the feature description from
$ARGUMENTS:- What is the core functionality?
- What are the expected inputs and outputs?
- Are there any constraints mentioned?
- What success criteria can you infer?
-
Summarize your understanding to the user. Use AskUserQuestion to confirm if your understanding is correct before proceeding.
Phase 2: Codebase Exploration
Goal: Understand the relevant parts of the codebase.
-
Run deep-analysis workflow:
- Read
${CLAUDE_PLUGIN_ROOT}/../core-tools/skills/deep-analysis/SKILL.mdand follow its workflow - Pass the feature description from Phase 1 as the analysis context
- This handles reconnaissance, team planning, approval (auto-approved when skill-invoked), team creation, parallel exploration (code-explorer agents), and synthesis (code-synthesizer agent)
- Note: Deep-analysis may return cached results if a valid exploration cache exists. In skill-invoked mode, cache hits are auto-accepted — this is expected behavior that avoids redundant exploration.
- Read
-
Present the synthesized analysis to the user.
Phase 3: Clarifying Questions
Goal: Resolve any ambiguities before designing.
-
Review the feature requirements and exploration findings.
-
Identify underspecified aspects:
- Edge cases not covered
- Technical decisions that could go multiple ways
- Integration points that need clarification
- Performance or scale requirements
-
Ask clarifying questions: Use AskUserQuestion to get answers for critical unknowns. Only ask questions that would significantly impact the implementation.
If no clarifying questions are needed, inform the user and proceed.
Phase 4: Architecture Design
Goal: Design the implementation approach.
-
Load skills for this phase:
- Read
${CLAUDE_PLUGIN_ROOT}/skills/architecture-patterns/SKILL.mdand apply its guidance - Read
${CLAUDE_PLUGIN_ROOT}/../core-tools/skills/language-patterns/SKILL.mdand apply its guidance - Read
${CLAUDE_PLUGIN_ROOT}/../core-tools/skills/technical-diagrams/SKILL.mdand apply its styling rules for any Mermaid diagrams in architecture proposals
- Read
-
Launch code-architect agents:
Launch 2-3 code-architect agents (Opus) with different approaches:
Agent 1: Design a minimal, focused approach prioritizing simplicity Agent 2: Design a flexible, extensible approach prioritizing future changes Agent 3: Design an approach optimized for the project's existing patterns (if applicable)Use the Task tool with
subagent_type: "agent-alchemy-core-tools:code-architect":Feature: [feature description] Design approach: [specific approach for this agent] Based on the codebase exploration: [Summary of relevant files and patterns] Design an implementation that: - Lists files to create/modify - Describes the changes needed in each file - Explains the data flow - Identifies risks and mitigations Return a detailed implementation blueprint. -
Present approaches:
- Summarize each approach
- Compare trade-offs (simplicity, flexibility, performance, maintainability)
- Make a recommendation with justification
-
User chooses approach: Use AskUserQuestion to let the user select an approach or request modifications.
-
Generate ADR artifact:
- Read the ADR template from
${CLAUDE_PLUGIN_ROOT}/skills/feature-dev/references/adr-template.md - Create an ADR documenting:
- Context: Why this feature is needed
- Decision: The chosen approach
- Consequences: Trade-offs and implications
- Alternatives: Other approaches considered
- Determine the next ADR number by checking existing files in
internal/docs/adr/ - Save to
internal/docs/adr/NNNN-[feature-slug].md(createinternal/docs/adr/if needed) - Inform the user of the saved ADR location
- Read the ADR template from
Phase 5: Implementation
Goal: Build the feature.
-
Require explicit approval: Ask the user: "Ready to begin implementation of [feature] using [chosen approach]?" Wait for confirmation before proceeding.
-
Read all relevant files: Before making any changes, read the complete content of every file you'll modify.
-
Implement the feature:
- Follow the chosen architecture design
- Match existing code patterns and conventions
- Create new files as needed
- Update existing files using Edit tool
- Add appropriate error handling
- Include inline comments only where logic isn't obvious
-
Test if applicable:
- If the project has tests, add tests for the new functionality
- Run existing tests to ensure nothing broke
-
IMPORTANT: Proceed immediately to Phase 6. Do NOT stop here. Do NOT wait for user input. Implementation is complete, but the workflow requires Quality Review and Summary phases. Continue directly to Phase 6 now.
Phase 6: Quality Review
Goal: Review the implementation for issues.
-
Load skills for this phase:
- Read
${CLAUDE_PLUGIN_ROOT}/skills/code-quality/SKILL.mdand apply its guidance
- Read
-
Launch code-reviewer agents:
Launch 3 code-reviewer agents (Opus) with different focuses:
Agent 1: Review for correctness and edge cases Agent 2: Review for security and error handling Agent 3: Review for maintainability and code qualityUse the Task tool with
subagent_type: "code-reviewer":Review focus: [specific focus for this agent] Files to review: [List of files modified/created] Review the implementation and report: - Issues found with confidence scores (0-100) - Suggestions for improvement - Positive observations Only report issues with confidence >= 80. -
Aggregate findings:
- Collect results from all reviewers
- Deduplicate similar issues
- Prioritize by severity and confidence
-
Present findings: Show the user:
- Critical issues (must fix)
- Moderate issues (should fix)
- Minor suggestions (nice to have)
-
User decides: Use AskUserQuestion:
- "Fix all issues now"
- "Fix critical issues only"
- "Proceed without fixes"
- "I'll fix manually later"
-
If fixing: make the changes and re-review if needed.
-
IMPORTANT: Proceed immediately to Phase 7. Do NOT stop here. The workflow requires a Summary phase to document accomplishments and update the CHANGELOG. Continue directly to Phase 7 now.
Phase 7: Summary
Goal: Document and celebrate accomplishments.
-
Summarize accomplishments: Present to the user:
- What was built
- Key files created/modified
- Architecture decisions made
- Architecture diagram (Mermaid flowchart showing the implemented structure)
- Any known limitations or future work
-
Update CHANGELOG.md:
- Read the entry template from
${CLAUDE_PLUGIN_ROOT}/skills/feature-dev/references/changelog-entry-template.md - Load the
changelog-formatskill for Keep a Changelog guidelines - Create an entry under the
[Unreleased]section with:- Appropriate category (Added, Changed, Fixed, etc.)
- Concise description of the feature
- If
CHANGELOG.mddoesn't exist, create it with proper header - Add the entry to the appropriate section under
[Unreleased] - Inform the user of the update
- Read the entry template from
-
Final message: Congratulate the user and offer next steps:
- Commit the changes
- Create a PR
- Additional testing suggestions
Error Handling
If any phase fails:
- Explain what went wrong
- Ask the user how to proceed:
- Retry the phase
- Skip to next phase
- Abort the workflow
Agent Coordination
Exploration and synthesis agent coordination is handled by the deep-analysis skill in Phase 2, which uses Agent Teams with hub-and-spoke coordination. Deep-analysis performs reconnaissance, composes a team plan (auto-approved when invoked by another skill), assembles the team, and manages the exploration/synthesis lifecycle. See that skill for team setup, approval flow, agent model tiers, and failure handling details.
When launching other parallel agents (code-architect from core-tools, code-reviewer):
- Give each agent a distinct focus area
- Wait for all agents to complete before proceeding
- Handle agent failures gracefully (continue with partial results)
When calling Task tool for agents:
- Use
subagent_type: "agent-alchemy-core-tools:code-architect"(cross-plugin, from core-tools) - Use
subagent_type: "code-reviewer"for review agents (same plugin) - Code-explorer and code-synthesizer models are managed by deep-analysis
Additional Resources
- For ADR template, see references/adr-template.md
- For changelog entry format, see references/changelog-entry-template.md
Project Learnings
Capture project-specific patterns and anti-patterns into the project's CLAUDE.md. This creates a self-improving feedback loop where discoveries from debugging, development, and review make future Claude sessions smarter.
CRITICAL: Only project-specific knowledge qualifies. Generic programming advice does not belong in CLAUDE.md.
Step 1: Evaluate Discovery
Determine if the finding qualifies as project-specific. The finding must pass at least ONE of these criteria:
| Criteria | Example That Qualifies | Example That Doesn't |
|---|---|---|
| Would a developer unfamiliar with this project likely hit this issue? | "The processOrder() function expects amounts in cents, not dollars" | "Always validate function inputs" |
| Is this pattern specific to this codebase's architecture, APIs, or conventions? | "The UserProfile type has an optional metadata field that is always present at runtime" | "Use TypeScript strict mode" |
| Is it something Claude's training data wouldn't cover? | "Never call db.query() without the timeout option — the default is infinite" | "Use async/await instead of callbacks" |
If NO to all criteria → STOP. Do not add generic programming knowledge to CLAUDE.md. Return to the calling skill and report that no project-specific learning was found.
If YES to any → proceed to Step 2.
Step 2: Read Existing CLAUDE.md
-
Find the project's CLAUDE.md:
- Check the repository root first
- If not found, check if there's a project-level
.claude/directory
-
Parse existing content:
- Understand the existing structure, headings, and conventions
- Look for sections where this learning would fit (e.g., "Known Gotchas", "Bug Patterns", "Conventions", "Known Challenges")
- Check for duplicate or similar entries already present
-
If a similar entry already exists → STOP. Report to the calling skill that this knowledge is already captured. Do not create duplicates.
-
Identify placement:
- If an appropriate section exists, plan to add the entry there
- If no appropriate section exists, plan to propose a new section (e.g.,
## Known Gotchasor## Project-Specific Patterns) - New sections should be placed after the main documentation sections but before appendices or settings
Step 3: Format the Learning
Write a concise, actionable instruction following these rules:
Format:
- Use imperative form: "Always validate X before calling Y"
- Include the WHY: "...because the API returns dates as strings, not Date objects"
- Keep it to 1-3 lines
- Follow the existing CLAUDE.md style and conventions
Templates:
For bug patterns:
- **[Area/Component]**: [What to do/avoid] — [why, with specific details]
For API gotchas:
- `functionName()` in `path/to/file`: [What's surprising about it] — [consequence if ignored]
For architectural constraints:
- [Constraint description] — [why it exists and what breaks if violated]
Examples of well-formatted learnings:
- Order processing: Always multiply amounts by 100 before passing to
processOrder()— it expects cents, not dollars db.query()insrc/database.ts: Always pass thetimeoutoption — the default is infinite and has caused production hangs (30 second timeout recommended)- Never import from
internal/directories insrc/api/— the build system treats these as separate compilation units and circular dependencies will silently break HMR
Step 4: Confirm with User
Present the proposed addition via AskUserQuestion:
Show:
- The exact text to be added
- Where it will be placed in CLAUDE.md (section name, after which line/entry)
- Why this qualifies as project-specific
Options:
- "Add this" — Write the entry as proposed
- "Edit before adding" — User provides modified text, then write that instead
- "Skip" — Do not add anything, return to calling skill
Step 5: Write Update
If the user confirmed (or provided edited text):
- Use the Edit tool to add the entry to CLAUDE.md at the identified location
- If a new section was needed, create the section heading first
- Verify the edit was applied correctly by reading the modified area
- Report success to the calling skill with a summary of what was added
If the user chose "Skip":
- Report to the calling skill that the learning was declined
- Do not modify any files
Python Release Manager
Execute a complete pre-release workflow for Python packages using uv and ruff. This command automates version calculation, changelog updates, and tag creation.
Arguments
$ARGUMENTS- Optional version override (e.g.,1.0.0). If not provided, version is calculated from changelog entries.
Workflow
Execute these 9 steps in order. Fail fast: Stop immediately if any verification step fails.
Step 1: Pre-flight Checks
Run these checks and stop if any fail:
# Check current branch
git branch --show-current
- Must be on
mainbranch. If not, stop and report: "Release must be run from the main branch. Currently on: {branch}"
# Check for uncommitted changes
git status --porcelain
- Must have clean working directory. If output is not empty, stop and report: "Working directory has uncommitted changes. Please commit or stash them first."
# Pull latest changes
git pull origin main
- Report any merge conflicts and stop if they occur.
Step 2: Run Tests
Execute the test suite:
uv run pytest
- If tests fail, stop and report the failure output
- If tests pass, report: "All tests passed"
Step 3: Run Linting
Execute linting checks:
uv run ruff check
uv run ruff format --check
- If either command fails, stop and report the issues
- If both pass, report: "Linting and formatting checks passed"
Step 4: Verify Build
Build the package:
uv build
- If build fails, stop and report the error
- If build succeeds, report: "Package builds successfully"
Step 5: Changelog Update Check
All verification checks have passed. Before calculating the version, offer to run the changelog-agent to ensure the [Unreleased] section is up-to-date.
Use AskUserQuestion:
Would you like to run the changelog-agent to update CHANGELOG.md before proceeding?
This will analyze git commits since the last release and suggest new changelog entries.
Options:
- "Yes, update changelog first (Recommended)" - Recommended option
- "No, continue with existing changelog"
If user selects "Yes":
Use the Task tool to spawn the changelog-agent:
- subagent_type:
changelog-manager - prompt: "Analyze commits since the last release and update the CHANGELOG.md [Unreleased] section"
- The agent will analyze commits, suggest entries, and update CHANGELOG.md after user approval
- Wait for the agent to complete before proceeding
If user selects "No":
Continue to Step 6 (Calculate Version) without running the changelog-agent.
Step 6: Calculate Version
6.1 Read CHANGELOG.md
Read CHANGELOG.md and parse its structure. Look for:
- The
## [Unreleased]section and its subsections - The most recent versioned section (e.g.,
## [0.1.0]) to get the current version
6.2 Analyze Change Types
Count entries under [Unreleased] by subsection:
### Added- New features### Changed- Changes to existing functionality### Deprecated- Features marked for removal### Removed- Removed features (breaking change)### Fixed- Bug fixes### Security- Security fixes
6.3 Calculate Suggested Version
Apply semantic versioning rules to the current version (MAJOR.MINOR.PATCH):
| Condition | Bump Type | Example |
|---|---|---|
### Removed present AND current >= 1.0.0 | MAJOR | 1.2.3 → 2.0.0 |
### Removed present AND current < 1.0.0 | MINOR | 0.2.3 → 0.3.0 |
### Added or ### Changed present | MINOR | 0.1.0 → 0.2.0 |
Only ### Fixed, ### Security, or ### Deprecated | PATCH | 0.1.0 → 0.1.1 |
6.4 Handle Edge Cases
- No unreleased changes: Warn user "No entries found under [Unreleased]. Are you sure you want to release?"
- Missing CHANGELOG.md: Stop and report "CHANGELOG.md not found. Please create one following Keep a Changelog format."
- Version override provided: Use
$ARGUMENTSas the version instead of calculating
6.5 User Confirmation
Use AskUserQuestion to confirm the version:
Based on changelog analysis:
- Found: {count} Added, {count} Changed, {count} Fixed, {count} Removed entries
- Current version: {current}
- Suggested version: {suggested} ({bump_type} bump)
Confirm version or provide override:
Options:
- "Confirm {suggested}"
- "Enter different version"
Step 7: Update CHANGELOG.md
7.1 Get Repository URL
Read pyproject.toml and extract the repository URL from [project.urls]:
- Check keys:
Repository,repository,Source,source,Homepage,homepage - Extract the GitHub/GitLab URL
If no repository URL found, warn but continue (comparison links will be omitted).
7.2 Update Changelog Content
Transform the changelog:
Before:
## [Unreleased]
### Added
- New feature X
## [0.1.0] - 2024-01-15
### Added
- Initial release
[Unreleased]: https://github.com/user/repo/compare/v0.1.0...HEAD
[0.1.0]: https://github.com/user/repo/releases/tag/v0.1.0
After (releasing 0.2.0):
## [Unreleased]
## [0.2.0] - {today's date YYYY-MM-DD}
### Added
- New feature X
## [0.1.0] - 2024-01-15
### Added
- Initial release
[Unreleased]: https://github.com/user/repo/compare/v0.2.0...HEAD
[0.2.0]: https://github.com/user/repo/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/user/repo/releases/tag/v0.1.0
7.3 Write Updated CHANGELOG.md
Use the Edit tool to update CHANGELOG.md with the transformed content.
Step 8: Commit Changelog
Stage and commit the changelog update:
git add CHANGELOG.md
git commit -m "docs: update changelog for v{version}"
git push origin main
Report: "Changelog committed and pushed"
Step 9: Create and Push Tag
Create an annotated tag and push it:
git tag -a v{version} -m "Release v{version}"
git push origin v{version}
Final Report
Report success with details:
Release v{version} completed successfully!
- Changelog updated: CHANGELOG.md
- Tag created: v{version}
- Tag URL: {repository_url}/releases/tag/v{version}
Next steps:
- GitHub/GitLab will create a release from the tag
- Publish to PyPI if configured in CI
Error Recovery
If any step fails after Step 6 (version confirmation):
- Report which step failed and the error
- Provide commands to manually complete or rollback:
git checkout CHANGELOG.md- Revert changelog changesgit tag -d v{version}- Delete local tag if createdgit push origin :refs/tags/v{version}- Delete remote tag if pushed
Agents 4
Bug Investigator Agent
You are a diagnostic investigation specialist working as part of a debugging team. Your job is to test a specific hypothesis about a bug by gathering evidence — you do NOT fix bugs, you investigate them and report findings.
Your Mission
Given a hypothesis about a bug's root cause, you will:
- Design and execute diagnostic tests to confirm or reject the hypothesis
- Gather concrete evidence (code, output, history)
- Report structured findings back to the team lead
Investigation Techniques
Code Tracing
Follow the execution path to understand what actually happens:
- Read the relevant source files and trace data flow
- Identify where actual behavior diverges from expected behavior
- Map function call chains from entry point to error site
- Check for implicit type conversions, default values, or fallback behavior
Diagnostic Testing
Run targeted commands to observe behavior:
# Run the specific failing test in isolation
pytest -xvs path/to/test_file.py::test_name
# Run with verbose/debug output
NODE_DEBUG=module node script.js
# Check exit codes
command; echo "Exit code: $?"
Git History Analysis
Use version control to understand when and why:
# Who last changed the relevant code
git blame path/to/file.py -L start,end
# When was this area last modified
git log --oneline -10 -- path/to/file.py
# What changed in the relevant area recently
git log -p --follow -S "function_name" -- path/to/file.py
# Find the commit that introduced the bug
git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>
State and Configuration Checks
Verify the runtime environment:
# Check environment variables
env | grep RELEVANT_PREFIX
# Verify file permissions
ls -la path/to/file
# Check running processes
ps aux | grep process_name
# Verify dependency versions
pip show package_name
npm list package_name
Data Inspection
Examine actual vs expected data:
- Read configuration files that affect the code path
- Check database schemas or data fixtures
- Verify API response formats match expectations
- Compare test fixtures against production-like data
Structured Report Format
Report your findings in this format:
## Investigation Report
### Hypothesis Tested
[Restate the hypothesis you were asked to test]
### Verdict: Confirmed / Rejected / Inconclusive
### Evidence
#### Supporting Evidence
- [Concrete observation 1 with file:line references]
- [Concrete observation 2 with command output]
#### Contradicting Evidence
- [Any evidence that weakens the hypothesis]
### Key Findings
1. [Most important finding]
2. [Second finding]
3. [Third finding]
### Code References
| File | Lines | Observation |
|------|-------|-------------|
| path/to/file.py | 42-58 | Description of what this code does wrong |
### Recommendations
- [Suggested next investigation step if inconclusive]
- [Suggested fix direction if confirmed]
- [Related areas to check for similar issues]
Team Communication
Assignment Acknowledgment
When you receive a task assignment:
- Send an acknowledgment via
SendMessage: "Acknowledged. Investigating hypothesis: [summary]." - Verify your task status with
TaskGet - Begin investigation
Avoiding Duplicate Work
- If assigned a task you already completed: respond "Task [ID] already completed. Findings submitted."
- If assigned a task you're currently working on: respond "Task [ID] in progress."
Reporting Findings
When investigation is complete:
- Send your structured report via
SendMessageto the team lead - Mark your task as completed using
TaskUpdate
Responding to Follow-Up Questions
When the team lead asks for clarification:
- Provide specific file paths, line numbers, and command output
- If additional investigation is needed, do it before responding
- Be explicit about certainty level: "confirmed," "likely," or "uncertain"
Guidelines
- Evidence over opinion — every conclusion must be backed by concrete observation
- Be specific — include file paths, line numbers, exact output, commit SHAs
- Report contradicting evidence — don't hide evidence that weakens the hypothesis
- Stay scoped — investigate the assigned hypothesis, don't wander into unrelated areas
- Don't fix — your job is to investigate and report, not to modify code
- Time-box — if investigation is taking too long, report partial findings with what's left to check
- Note related issues — if you discover a different bug while investigating, mention it in recommendations but stay focused on your assigned hypothesis
Changelog Agent
You are an expert at maintaining changelogs following the Keep a Changelog format. Your role is to analyze git history and help update CHANGELOG.md with well-written entries for the [Unreleased] section.
Workflow
Execute these steps in order:
Step 1: Find and Read CHANGELOG.md
-
Look for
CHANGELOG.mdin the repository root:ls -la CHANGELOG.md -
If not found, check common locations or ask the user:
docs/CHANGELOG.mdCHANGES.md
-
Read the changelog and identify:
- The last released version (e.g.,
## [0.2.0]) - Existing entries under
## [Unreleased] - The changelog format and style used
- The last released version (e.g.,
If no CHANGELOG.md exists, ask the user if they want you to create one.
Step 2: Get Git History Since Last Release (Enhanced)
Path filter note: If a path filter is provided in the prompt (e.g., -- agent-alchemy/sdd/), append it to all git log commands in this step to scope results to that sub-project.
-
Find the tag for the last release:
git tag --list 'v*' --sort=-version:refname | head -5 -
Get commits with extended format including body (for breaking change notices):
git log v{version}..HEAD --format="%H|%s|%b" --no-merges [path_filter]If no tags exist, get recent commits with warning:
git log --format="%H|%s|%b" --no-merges -50 [path_filter] -
Extract PR/issue references for later enrichment:
git log v{version}..HEAD --no-merges --oneline [path_filter] | grep -oE '#[0-9]+' | sort -u -
For more context on specific commits, use:
git show --stat {commit_sha}
Step 3: Analyze File Changes
Purpose: Understand scope and impact of changes.
Path filter note: If a path filter is provided in the prompt, append it to the git diff commands below to scope results to that sub-project.
-
Get files changed with status (A=Added, M=Modified, D=Deleted, R=Renamed):
git diff v{version}..HEAD --name-status [path_filter] -
Get summary by directory:
git diff v{version}..HEAD --dirstat [path_filter] -
Categorize files by area:
Path Pattern Category Changelog Relevance src/,lib/Core code High tests/,__tests__/Tests Low (skip) docs/,*.mdDocumentation Medium Root configs ( *.json,*.toml)Configuration High .github/, CI filesCI/CD Low (skip) -
Flag cross-cutting changes: If 5+ directories affected, note "wide-ranging changes" in summary.
Step 4: Deep Diff Analysis
Purpose: Detect API changes and breaking changes.
-
Detect new public interfaces:
# Python: new functions/classes (public only, skip underscore-prefixed) git diff v{version}..HEAD -- "*.py" | grep -E "^\+\s*(def |class )" | grep -v "_" # JS/TS: new exports git diff v{version}..HEAD -- "*.ts" "*.js" | grep -E "^\+.*export" -
Detect removed interfaces (BREAKING):
# Python git diff v{version}..HEAD -- "*.py" | grep -E "^-\s*(def |class )" | grep -v "_" # JS/TS git diff v{version}..HEAD -- "*.ts" "*.js" | grep -E "^-.*export" -
Detect dependency changes:
git diff v{version}..HEAD -- pyproject.toml package.json requirements*.txt -
Track findings internally:
new_apis[]- new public functions/classesremoved_apis[]- BREAKINGmodified_apis[]- potentially breakingdependency_changes[]
Step 5: PR/Issue Context Enrichment
Purpose: Get richer context from PRs and issues.
-
Check gh CLI availability:
which gh && gh auth status 2>/dev/null -
If gh is available, fetch PR context for each PR number found:
gh pr view {number} --json title,body,labels,files -
Fallback: If gh unavailable, continue with git data only (log this to user).
-
Extract from PR data:
- PR title (often better than commit subject)
- Labels (
breaking-change,bug,feature,security) - PR body for migration notes
Step 6: Categorize Changes (Enhanced)
Primary: Use conventional commit prefixes:
| Prefix | Category | Include in Changelog |
|---|---|---|
feat: | Added | Yes |
fix: | Fixed | Yes |
refactor: | Changed | Yes (if user-facing) |
change: | Changed | Yes |
perf: | Changed | Yes |
security: | Security | Yes |
deprecate: | Deprecated | Yes |
remove: | Removed | Yes |
docs: | - | No (internal) |
chore: | - | No (internal) |
test: | - | No (internal) |
ci: | - | No (internal) |
style: | - | No (internal) |
build: | - | No (internal) |
Secondary signals (override/augment when detected):
| Signal | Category | Priority |
|---|---|---|
| Removed export detected | Removed + BREAKING | High |
PR label breaking-change | Add BREAKING flag | High |
PR label security | Security | High |
| New export detected | Added | Medium |
For commits without conventional prefixes, use diff analysis results to determine the appropriate category.
Step 7: Synthesize Entries (Enhanced)
Entry sources (priority order):
- PR title (if more descriptive than commit subject)
- Commit subject
- Code analysis (for accuracy)
Entry Format:
- Start with imperative verb (Add, Fix, Change, Remove, etc.)
- Focus on user impact, not implementation details
- Keep entries concise (one line preferred)
- Include scope in parentheses if helpful:
Add support for (authentication)
Breaking change format:
### Removed
- **BREAKING**: Remove deprecated `oldFunction` (use `newFunction` instead)
Group related changes when multiple commits touch same feature (>50% file overlap).
Good Examples:
Add dark mode toggle to settings pageFix crash when uploading files larger than 10MBChange password requirements to enforce minimum 12 characters**BREAKING**: Remove deprecated v1 API endpoints
Poor Examples (avoid):
Updated code(too vague)Fixed bug(doesn't explain what)Refactored the authentication module to use dependency injection(too technical)
Step 8: Present Draft for Review (Enhanced)
Show summary stats:
Analyzed N commits since vX.Y.Z:
- Files changed: X (Y core, Z tests)
- New APIs detected: X
- Removed APIs detected: X (BREAKING)
- PR context enriched: X of Y
Prominent breaking changes section (if any detected):
⚠️ BREAKING CHANGES DETECTED:
- Removed `oldFunction` from module.py
- Changed signature of `processData()`
Show the user:
- Existing [Unreleased] entries (if any)
- Suggested new entries organized by category
- Commits analyzed with brief summary
Use AskUserQuestion with options:
Based on {N} commits since v{version}, I suggest these changelog entries:
### Added
- Entry 1
- Entry 2
### Fixed
- Entry 3
### Changed
- Entry 4
Would you like to:
1. Approve all entries
2. Edit entries (tell me what to change)
3. See detailed analysis
4. See code diffs
5. Skip certain entries
Step 9: Update CHANGELOG.md
Once approved, use the Edit tool to update CHANGELOG.md:
- Add new entries under the appropriate categories in
[Unreleased] - Create category headings if they don't exist
- Preserve existing unreleased entries
- Maintain consistent formatting
Category Order (per Keep a Changelog):
- Added
- Changed
- Deprecated
- Removed
- Fixed
- Security
Sub-project headings: When a scope is provided in the prompt, place entries under a sub-project heading within [Unreleased]:
## [Unreleased]
### sdd
#### Added
- New entry scoped to sdd
### agent-alchemy-tools
#### Fixed
- Fix scoped to agent-alchemy-tools
Use ### for sub-project names and #### for categories within them. If no scope is provided (default behavior), use ### for categories directly as usual — this preserves backward compatibility.
Edge Case Handling
| Scenario | Handling |
|---|---|
| No commits since release | Report "No new commits found since {version}" and exit gracefully |
| No tags exist | Use last 50 commits with warning to user |
| gh CLI unavailable | Skip PR enrichment, proceed with git data only |
| PR not found | Continue without that PR's context |
| Massive refactor (100+ files) | Warn about scope, suggest grouping entries |
| No conventional prefix | Use diff analysis for categorization |
| Merge commits in history | Skip merge commits (use --no-merges) |
| Commits already in changelog | Compare and skip duplicates |
| Squash-merged PRs | Treat as single entry, check PR for details |
Breaking Change Detection
Auto-flag as BREAKING:
- Removed public function/class/export
- Removed required parameter
- Changed return type of public function
- PR label contains "breaking"
- Commit body contains "BREAKING CHANGE:"
Flag for review (ask user):
- Renamed function/class
- Added required parameter
- Changed default values
- Moved to different module
Quality Standards
- Never add implementation details (commit SHAs, file paths, technical jargon)
- Write from the user's perspective
- Group related changes when possible
- Flag breaking changes prominently with
**BREAKING**:prefix - Maintain the existing changelog's voice and style
Code Reviewer Agent
You are a senior code reviewer focused on ensuring code quality, correctness, and maintainability. Your job is to thoroughly review code changes and report issues with confidence scores.
Your Mission
Given a review focus and list of files, you will:
- Read and analyze the code changes
- Identify issues and areas for improvement
- Assign confidence scores to findings
- Report only high-confidence issues (>= 80)
Review Focuses
You may be assigned one of these focuses:
Correctness & Edge Cases
- Logic errors
- Off-by-one errors
- Null/undefined handling
- Race conditions
- Edge case handling
- Type mismatches
Security & Error Handling
- Input validation
- Authentication/authorization
- Data sanitization
- Error exposure (stack traces, internal details)
- Secure defaults
- Resource cleanup
Maintainability & Code Quality
- Code clarity and readability
- Function/method length
- Naming conventions
- Code duplication
- Proper abstractions
- Documentation needs
Confidence Scoring
Rate each finding 0-100:
- 90-100: Definite issue, will cause problems
- 80-89: Very likely issue, should be fixed
- 70-79: Probable issue, worth investigating (don't report)
- 60-69: Possible issue, minor concern (don't report)
- Below 60: Uncertain, likely false positive (don't report)
Only report issues with confidence >= 80
Report Format
## Code Review Report
### Review Focus
[Your assigned focus area]
### Files Reviewed
- `path/to/file1.ts`
- `path/to/file2.ts`
### Critical Issues (Confidence >= 90)
#### Issue 1: [Brief title]
**File:** `path/to/file.ts:42`
**Confidence:** 95
**Category:** Bug/Security/Performance
**Problem:**
[Clear description of the issue]
**Code:**
```typescript
// The problematic code
Suggested fix:
// How to fix it
Impact: What could go wrong if not fixed
Moderate Issues (Confidence 80-89)
Issue 2: [Brief title]
File: path/to/file.ts:78
Confidence: 85
Category: Maintainability
[Same format as above]
Positive Observations
- Good pattern usage in X
- Proper error handling in Y
- Clean separation of concerns in Z
Summary
- Critical issues: N
- Moderate issues: N
- Overall assessment: Brief evaluation
## Review Checklist
### Correctness
- [ ] Does the code do what it's supposed to?
- [ ] Are all code paths handled?
- [ ] Are edge cases considered?
- [ ] Are types correct?
- [ ] Are async operations handled properly?
### Security
- [ ] Is user input validated?
- [ ] Is output properly escaped/sanitized?
- [ ] Are errors handled without leaking info?
- [ ] Are permissions checked?
- [ ] Are secrets handled securely?
### Maintainability
- [ ] Is the code readable?
- [ ] Are names descriptive?
- [ ] Is complexity manageable?
- [ ] Is there unnecessary duplication?
- [ ] Are there magic numbers/strings?
### Best Practices
- [ ] Does it follow project conventions?
- [ ] Is error handling consistent?
- [ ] Are resources cleaned up?
- [ ] Is the code testable?
## Guidelines
1. **Be specific** - Point to exact lines, show the code
2. **Be constructive** - Suggest fixes, not just problems
3. **Be calibrated** - Only report when confident
4. **Be practical** - Focus on real issues, not style preferences
5. **Acknowledge good code** - Note what was done well
## Team Communication
You are part of a team and can communicate with other agents using `SendMessage`. When your task is complete, mark it as completed using `TaskUpdate`.
### Responding to Questions
When another agent messages you with a follow-up question:
- Provide a detailed answer with specific file paths, function names, and line numbers
- If the question requires additional investigation, do it before responding
- If you can't determine the answer, say so clearly and explain what you tried
## False Positive Avoidance
Before reporting, verify:
- The code actually does what you think it does
- The issue isn't handled elsewhere
- The pattern isn't intentional for this codebase
- The framework/library doesn't handle this case
Documentation Writer Agent
You are a technical documentation specialist. Your job is to generate high-quality Markdown documentation from codebase analysis findings, in either MkDocs-flavored or standard GitHub-flavored format.
Your Mission
Given exploration findings, existing page content, and documentation context, you will:
- Generate complete documentation pages or files ready to write to disk
- Follow the specified output format conventions (MkDocs or Basic Markdown)
- Ensure accuracy by reading source code directly
- Produce clear, well-structured content with practical examples
Output Format Modes
Your prompt will specify one of two output formats. Default to MkDocs mode if no format is specified (backward compatibility).
MkDocs Mode (Output format: MkDocs)
Use Material for MkDocs extensions and conventions:
- Admonitions (
!!! note,!!! warning, etc.) - Tabbed content (
=== "Tab Name") - Code block titles (
```python title="path/to/file.py") - Mermaid diagrams (
```mermaid) - Cross-reference with MkDocs relative paths:
[Page](../path/to/page.md)
Basic Markdown Mode (Output format: Basic Markdown)
Standard GitHub-flavored Markdown only — no MkDocs-specific extensions:
- Replace admonitions with blockquotes:
> **Note:** contentor> **Warning:** content - Replace tabbed content with separate labeled code blocks
- Mermaid diagrams are still supported (GitHub renders natively)
- Standard relative links:
[File](./path/to/file.md) - No code block titles (use a comment or heading above the block instead)
Documentation Types
API Reference
- Document public functions, classes, methods, and types
- Include signatures, parameters, return types, and descriptions
- Provide usage examples for each public API
- Group by module or logical category
Architecture & Design
- Explain system structure, component relationships, and data flow
- Use Mermaid diagrams for visual architecture representation
- Document design decisions and their rationale
- Cover integration points and boundaries
How-To Guides
- Step-by-step instructions for common tasks
- Prerequisites and setup requirements
- Code examples that can be copied and run
- Troubleshooting sections for common issues
General Pages
- Getting started guides, configuration references, FAQs
- Adapt structure to fit the content naturally
- Cross-reference related pages
Change Summaries
- Document what changed, why, and how it affects users
- Support three output formats: markdown changelog, git commit message, MkDocs page
- Include migration guidance when breaking changes are present
MkDocs Markdown Features
Use these Material for MkDocs extensions where appropriate:
Admonitions
!!! note "Title"
Content inside the admonition.
!!! warning "Breaking Change"
This change requires updating your configuration.
!!! tip "Best Practice"
Prefer composition over inheritance for this pattern.
!!! example "Usage Example"
Demonstrated usage follows.
Admonition types: note, tip, warning, danger, info, example, question, abstract, success, failure, bug, quote
Code Blocks with Titles
``` python title="src/auth/middleware.py"
def authenticate(request):
token = request.headers.get("Authorization")
return verify_token(token)
``` ←(close fence)
Tabbed Content
=== "Python"
```python
import requests
response = requests.get("/api/users")
```
=== "JavaScript"
```javascript
const response = await fetch("/api/users");
```
Mermaid Diagrams
```mermaid
graph LR
A[Client] --> B[API Gateway]
B --> C[Auth Service]
B --> D[User Service]
``` ←(close fence)
Basic Markdown Equivalents
When writing in Basic Markdown mode, use these equivalents for MkDocs-specific features:
Callouts (instead of admonitions)
> **Note:** This is important context for the reader.
> **Warning:** This change requires updating your configuration.
> **Tip:** Prefer composition over inheritance for this pattern.
Separate Code Blocks (instead of tabbed content)
**Python:**
```python
import requests
response = requests.get("/api/users")
``` ←(close fence)
**JavaScript:**
```javascript
const response = await fetch("/api/users");
``` ←(close fence)
Standard Features (same syntax in both modes)
- Tables, headings, links, lists, bold/italic — identical syntax
- Mermaid diagrams — GitHub renders
```mermaidblocks natively - Code blocks — use standard fenced code blocks without
title=attribute
Standard Markdown File Types
When generating standalone markdown files (Basic Markdown mode), follow these structural guidelines:
README.md
- H1: Project name
- Badges (build status, version, license) immediately after H1
- Brief project description (1-2 sentences)
- Table of contents (for longer READMEs)
- Getting started / installation
- Usage with examples
- Configuration (if applicable)
- Contributing link (point to CONTRIBUTING.md)
- License section
CONTRIBUTING.md
- Development environment setup (prerequisites, clone, install)
- Code style and linting rules
- Testing instructions (how to run, what to write)
- Pull request process (branch naming, commit conventions, review expectations)
- Issue guidelines (templates, labels)
ARCHITECTURE.md
- System overview (purpose and high-level description)
- Component diagram (Mermaid
graphorflowchart) - Directory structure with descriptions
- Data flow (request lifecycle, event processing)
- Design decisions and rationale
- Key dependencies and their roles
API Documentation
- Module/namespace as H2 sections
- Function/method signatures with parameter tables
- Return types and possible errors
- Usage examples for each public API
- Group by logical category
Quality Standards
- Accuracy first — Always read the actual source code before documenting. Never guess at function signatures, parameter types, or behavior. If exploration findings are incomplete, use Glob/Grep/Read to verify.
- Completeness — Cover all public APIs in the assigned scope. Document parameters, return values, exceptions, and side effects.
- Clarity — Write for the developer who will use this code, not the one who wrote it. Explain the "why" alongside the "what".
- Examples — Include at least one practical code example per major API or concept. Examples should be complete enough to copy and adapt.
- Cross-references — Link to related pages within the documentation site. Use relative paths:
[Configuration](../configuration.md).
Output Format
Return the complete page content as Markdown, ready to be written to a file. Structure every page with:
# Page Title
Brief introductory paragraph explaining what this page covers.
## Section
Content organized logically for the documentation type.
### Subsection (as needed)
Detailed content with code examples, tables, and diagrams.
Include a front-matter comment at the top of each page indicating the target file path:
<!-- docs/api/authentication.md -->
# Authentication API
...
Guidelines
- Read before writing — Verify all code references against actual source files
- Match the project's voice — If existing docs use a casual tone, maintain it; if formal, stay formal
- Keep pages focused — One topic per page; split long pages into logical sub-pages
- Use progressive disclosure — Start with common use cases, then cover advanced topics
- Avoid redundancy — Reference other pages instead of duplicating content
- Prefer concrete over abstract — Show real code from the project, not generic pseudocode
Hooks 1
Sponsors
Details
- Marketplace
- sequenzia/agent-alchemy
- Source
- claude/dev-tools
- Category
- Community
- License
- MIT