init bmad
This commit is contained in:
pukpuk
38
.gitignore
vendored
Normal file
38
.gitignore
vendored
Normal file
@@ -0,0 +1,38 @@
|
||||
# BMad Method
|
||||
.bmad-core
|
||||
.claude/commands/BMad
|
||||
docs/
|
||||
|
||||
# Node modules
|
||||
node_modules/
|
||||
|
||||
# Environment variables
|
||||
.env
|
||||
.env.local
|
||||
.env.*.local
|
||||
|
||||
# IDE
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Logs
|
||||
*.log
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
|
||||
# Build output
|
||||
dist/
|
||||
build/
|
||||
*.tsbuildinfo
|
||||
|
||||
# Temporary files
|
||||
tmp/
|
||||
temp/
|
||||
21
.mcp.json
Normal file
21
.mcp.json
Normal file
@@ -0,0 +1,21 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"serena": {
|
||||
"type": "stdio",
|
||||
"command": "uvx",
|
||||
"args": [
|
||||
"--from",
|
||||
"git+https://github.com/oraios/serena",
|
||||
"serena",
|
||||
"start-mcp-server",
|
||||
"--context",
|
||||
"ide-assistant",
|
||||
"--enable-web-dashboard",
|
||||
"false",
|
||||
"--project",
|
||||
"/Users/pukpuk/claude-code-tools"
|
||||
],
|
||||
"env": {}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,50 +1,199 @@
|
||||
# [PROJECT_NAME] Constitution
|
||||
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
|
||||
<!--
|
||||
Sync Impact Report:
|
||||
- Version: 1.0.0 (Initial constitution)
|
||||
- Created: 2025-10-08
|
||||
- Type: Initial creation
|
||||
- Modified Principles: N/A (new document)
|
||||
- Added Sections: All sections (initial creation)
|
||||
- Removed Sections: None
|
||||
- Templates Status:
|
||||
✅ plan-template.md - Constitution Check section aligns with principles
|
||||
✅ spec-template.md - Requirements sections align with quality standards
|
||||
✅ tasks-template.md - Task structure supports principle-driven development
|
||||
- Follow-up TODOs: None
|
||||
-->
|
||||
|
||||
# Claude Code Tools Constitution
|
||||
|
||||
## Core Principles
|
||||
|
||||
### [PRINCIPLE_1_NAME]
|
||||
<!-- Example: I. Library-First -->
|
||||
[PRINCIPLE_1_DESCRIPTION]
|
||||
<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
|
||||
### I. Tool-First Architecture
|
||||
|
||||
### [PRINCIPLE_2_NAME]
|
||||
<!-- Example: II. CLI Interface -->
|
||||
[PRINCIPLE_2_DESCRIPTION]
|
||||
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
|
||||
Every feature MUST be designed as a standalone, reusable tool that enhances Claude Code's capabilities. Tools MUST be:
|
||||
- Self-contained with clear, single responsibility
|
||||
- Independently testable and documented
|
||||
- Composable with other tools in the ecosystem
|
||||
- Designed for both CLI and programmatic use
|
||||
|
||||
### [PRINCIPLE_3_NAME]
|
||||
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
|
||||
[PRINCIPLE_3_DESCRIPTION]
|
||||
<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
|
||||
**Rationale**: Claude Code's power comes from its extensibility. Tools that follow this principle ensure maximum reusability and maintainability across the ecosystem.
|
||||
|
||||
### [PRINCIPLE_4_NAME]
|
||||
<!-- Example: IV. Integration Testing -->
|
||||
[PRINCIPLE_4_DESCRIPTION]
|
||||
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
|
||||
### II. Developer Experience (DX) Priority
|
||||
|
||||
### [PRINCIPLE_5_NAME]
|
||||
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
|
||||
[PRINCIPLE_5_DESCRIPTION]
|
||||
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
|
||||
All tools, hooks, and agents MUST prioritize developer experience:
|
||||
- Clear, intuitive APIs and interfaces
|
||||
- Comprehensive documentation with examples
|
||||
- Helpful error messages that guide users to solutions
|
||||
- Progressive disclosure: simple by default, powerful when needed
|
||||
|
||||
## [SECTION_2_NAME]
|
||||
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
|
||||
**Rationale**: Claude Code users are developers. Poor DX creates friction and reduces adoption. Every interaction should feel effortless and empowering.
|
||||
|
||||
[SECTION_2_CONTENT]
|
||||
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
|
||||
### III. Hook-Driven Extensibility
|
||||
|
||||
## [SECTION_3_NAME]
|
||||
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
|
||||
Extensibility MUST be achieved through well-defined hooks:
|
||||
- Hooks MUST have clear lifecycle events and contracts
|
||||
- Hook execution MUST be predictable and debuggable
|
||||
- Hooks MUST support both sync and async operations where appropriate
|
||||
- Hook failures MUST be graceful and informative
|
||||
|
||||
[SECTION_3_CONTENT]
|
||||
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
|
||||
**Rationale**: Hooks are the foundation of Claude Code's extensibility. Well-designed hooks enable users to customize behavior without modifying core code.
|
||||
|
||||
### IV. Agent Specialization
|
||||
|
||||
AI agents MUST be purpose-built for specific domains:
|
||||
- Each agent MUST have a clearly defined scope and responsibility
|
||||
- Agents MUST be context-aware and use appropriate tools
|
||||
- Agent prompts MUST be version-controlled and testable
|
||||
- Agents MUST provide clear reasoning and actionable outputs
|
||||
|
||||
**Rationale**: General-purpose agents lead to unpredictable behavior. Specialized agents deliver consistent, high-quality results in their domain.
|
||||
|
||||
### V. Test-First Development (NON-NEGOTIABLE)
|
||||
|
||||
Testing MUST precede implementation:
|
||||
- Write tests → Get user approval → Verify tests fail → Implement
|
||||
- All tools MUST have unit tests for core functionality
|
||||
- Integration tests MUST validate tool composition and hook interactions
|
||||
- Agent behavior MUST be validated through prompt testing and output validation
|
||||
|
||||
**Rationale**: Claude Code tools are foundational infrastructure. Bugs cascade to all users. TDD ensures reliability and prevents regressions.
|
||||
|
||||
### VI. Observability & Debuggability
|
||||
|
||||
All components MUST be observable and debuggable:
|
||||
- Tools MUST log operations at appropriate levels (debug, info, warn, error)
|
||||
- Hooks MUST emit events for monitoring and debugging
|
||||
- Agents MUST expose reasoning and decision-making processes
|
||||
- Performance metrics MUST be measurable and trackable
|
||||
|
||||
**Rationale**: When tools fail in production, developers need visibility. Observability transforms frustrating debugging sessions into quick fixes.
|
||||
|
||||
### VII. Simplicity & YAGNI
|
||||
|
||||
Complexity MUST be justified:
|
||||
- Start with the simplest solution that solves the problem
|
||||
- Add complexity only when demonstrable need exists
|
||||
- Prefer composition over inheritance
|
||||
- Avoid premature optimization and feature bloat
|
||||
|
||||
**Rationale**: Claude Code's strength is its elegant simplicity. Every line of complexity is technical debt that slows development and confuses users.
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Specification-Driven Development
|
||||
|
||||
All features MUST follow the spec workflow:
|
||||
|
||||
1. **Specification Phase**: Create detailed spec using `/speckit.specify`
|
||||
- Define user scenarios and acceptance criteria
|
||||
- Identify functional requirements
|
||||
- Clarify ambiguities with `/speckit.clarify`
|
||||
|
||||
2. **Planning Phase**: Generate implementation plan using `/speckit.plan`
|
||||
- Research existing patterns and dependencies
|
||||
- Design data models and contracts
|
||||
- Validate against constitution principles
|
||||
|
||||
3. **Task Breakdown**: Generate actionable tasks using `/speckit.tasks`
|
||||
- Organize by user story for independent delivery
|
||||
- Mark parallel execution opportunities
|
||||
- Define clear dependencies
|
||||
|
||||
4. **Implementation**: Execute tasks using `/speckit.implement`
|
||||
- Write tests first (TDD)
|
||||
- Implement to pass tests
|
||||
- Document as you build
|
||||
|
||||
5. **Quality Assurance**: Validate using `/speckit.analyze`
|
||||
- Cross-artifact consistency checks
|
||||
- Constitution compliance verification
|
||||
- Integration testing validation
|
||||
|
||||
### Code Review Requirements
|
||||
|
||||
All pull requests MUST:
|
||||
- Include tests that validate the feature
|
||||
- Pass all existing tests without modification (unless explicitly refactoring)
|
||||
- Update documentation for user-facing changes
|
||||
- Include examples for new tools, hooks, or agents
|
||||
- Demonstrate constitution compliance (especially Principles I-VII)
|
||||
|
||||
### Version Control & Breaking Changes
|
||||
|
||||
Version numbers MUST follow semantic versioning (MAJOR.MINOR.PATCH):
|
||||
- **MAJOR**: Breaking changes to tool APIs, hook contracts, or agent interfaces
|
||||
- **MINOR**: New tools, hooks, or agents; backward-compatible enhancements
|
||||
- **PATCH**: Bug fixes, documentation updates, non-functional improvements
|
||||
|
||||
Breaking changes MUST:
|
||||
- Be documented in CHANGELOG.md with migration guides
|
||||
- Provide deprecation warnings for at least one MINOR version before removal
|
||||
- Include automated migration scripts when feasible
|
||||
|
||||
## Quality Standards
|
||||
|
||||
### Documentation Requirements
|
||||
|
||||
All components MUST include:
|
||||
- **README.md**: Overview, installation, quick start
|
||||
- **API Documentation**: Function signatures, parameters, return values, examples
|
||||
- **Usage Examples**: Real-world scenarios demonstrating common use cases
|
||||
- **Troubleshooting Guide**: Common errors and solutions
|
||||
|
||||
### Performance Standards
|
||||
|
||||
Tools MUST meet these performance targets:
|
||||
- CLI commands: <500ms startup time for simple operations
|
||||
- Hook execution: <100ms overhead per hook invocation
|
||||
- Agent responses: <10s for standard operations (excluding LLM latency)
|
||||
- Memory footprint: <100MB for typical tool execution
|
||||
|
||||
### Security Requirements
|
||||
|
||||
All components MUST:
|
||||
- Validate all user inputs to prevent injection attacks
|
||||
- Never log or expose sensitive information (API keys, credentials, PII)
|
||||
- Use secure defaults (e.g., restrictive file permissions)
|
||||
- Document security considerations for user-configurable options
|
||||
|
||||
## Governance
|
||||
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
|
||||
|
||||
[GOVERNANCE_RULES]
|
||||
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
|
||||
### Constitutional Authority
|
||||
|
||||
**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
|
||||
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
|
||||
This constitution supersedes all other project practices and guidelines. When conflicts arise between this constitution and other documentation, the constitution takes precedence.
|
||||
|
||||
### Amendment Process
|
||||
|
||||
Constitutional amendments MUST:
|
||||
1. Be proposed via GitHub issue with clear rationale
|
||||
2. Include impact analysis on existing tools, hooks, and agents
|
||||
3. Receive approval from project maintainers
|
||||
4. Include migration plan for affected components
|
||||
5. Update dependent templates and documentation
|
||||
|
||||
### Compliance Review
|
||||
|
||||
All feature specifications MUST pass a Constitution Check (see plan-template.md) before implementation begins. The check validates:
|
||||
- Alignment with Core Principles (I-VII)
|
||||
- Adherence to Development Workflow
|
||||
- Compliance with Quality Standards
|
||||
- Security Requirements satisfaction
|
||||
|
||||
### Version Management & Documentation
|
||||
|
||||
Constitution changes MUST:
|
||||
- Increment version number according to semantic versioning
|
||||
- Update RATIFICATION_DATE only for initial adoption
|
||||
- Update LAST_AMENDED_DATE for all subsequent changes
|
||||
- Include Sync Impact Report (HTML comment at top of file) detailing all changes
|
||||
|
||||
**Version**: 1.0.0 | **Ratified**: 2025-10-08 | **Last Amended**: 2025-10-08
|
||||
|
||||
@@ -31,7 +31,45 @@
|
||||
|
||||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
||||
|
||||
[Gates determined based on constitution file]
|
||||
**Principle I - Tool-First Architecture**
|
||||
- [ ] Feature designed as standalone, reusable tool
|
||||
- [ ] Single responsibility clearly defined
|
||||
- [ ] Independently testable and documented
|
||||
- [ ] Supports both CLI and programmatic use
|
||||
|
||||
**Principle II - Developer Experience (DX) Priority**
|
||||
- [ ] API/interface is clear and intuitive
|
||||
- [ ] Documentation includes examples
|
||||
- [ ] Error messages guide users to solutions
|
||||
- [ ] Simple by default, powerful when needed
|
||||
|
||||
**Principle III - Hook-Driven Extensibility**
|
||||
- [ ] Uses well-defined hooks with clear contracts (if applicable)
|
||||
- [ ] Hook execution is predictable and debuggable
|
||||
- [ ] Hook failures are graceful and informative
|
||||
|
||||
**Principle IV - Agent Specialization**
|
||||
- [ ] Agent has clearly defined scope (if applicable)
|
||||
- [ ] Agent is context-aware with appropriate tools
|
||||
- [ ] Agent prompts are version-controlled and testable
|
||||
|
||||
**Principle V - Test-First Development (NON-NEGOTIABLE)**
|
||||
- [ ] Tests will be written before implementation
|
||||
- [ ] Unit tests cover core functionality
|
||||
- [ ] Integration tests validate tool composition/hook interactions
|
||||
- [ ] Agent behavior validated through prompt/output testing (if applicable)
|
||||
|
||||
**Principle VI - Observability & Debuggability**
|
||||
- [ ] Appropriate logging levels defined (debug, info, warn, error)
|
||||
- [ ] Events emitted for monitoring (if applicable)
|
||||
- [ ] Reasoning/decision-making processes exposed (for agents)
|
||||
- [ ] Performance metrics measurable
|
||||
|
||||
**Principle VII - Simplicity & YAGNI**
|
||||
- [ ] Simplest solution chosen
|
||||
- [ ] Complexity justified (see Complexity Tracking if violations exist)
|
||||
- [ ] Composition preferred over inheritance
|
||||
- [ ] No premature optimization or feature bloat
|
||||
|
||||
## Project Structure
|
||||
|
||||
|
||||
Reference in New Issue
Block a user