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
|
## Core Principles
|
||||||
|
|
||||||
### [PRINCIPLE_1_NAME]
|
### I. Tool-First Architecture
|
||||||
<!-- 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 -->
|
|
||||||
|
|
||||||
### [PRINCIPLE_2_NAME]
|
Every feature MUST be designed as a standalone, reusable tool that enhances Claude Code's capabilities. Tools MUST be:
|
||||||
<!-- Example: II. CLI Interface -->
|
- Self-contained with clear, single responsibility
|
||||||
[PRINCIPLE_2_DESCRIPTION]
|
- Independently testable and documented
|
||||||
<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
|
- Composable with other tools in the ecosystem
|
||||||
|
- Designed for both CLI and programmatic use
|
||||||
|
|
||||||
### [PRINCIPLE_3_NAME]
|
**Rationale**: Claude Code's power comes from its extensibility. Tools that follow this principle ensure maximum reusability and maintainability across the ecosystem.
|
||||||
<!-- 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 -->
|
|
||||||
|
|
||||||
### [PRINCIPLE_4_NAME]
|
### II. Developer Experience (DX) Priority
|
||||||
<!-- Example: IV. Integration Testing -->
|
|
||||||
[PRINCIPLE_4_DESCRIPTION]
|
|
||||||
<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
|
|
||||||
|
|
||||||
### [PRINCIPLE_5_NAME]
|
All tools, hooks, and agents MUST prioritize developer experience:
|
||||||
<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
|
- Clear, intuitive APIs and interfaces
|
||||||
[PRINCIPLE_5_DESCRIPTION]
|
- Comprehensive documentation with examples
|
||||||
<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
|
- Helpful error messages that guide users to solutions
|
||||||
|
- Progressive disclosure: simple by default, powerful when needed
|
||||||
|
|
||||||
## [SECTION_2_NAME]
|
**Rationale**: Claude Code users are developers. Poor DX creates friction and reduces adoption. Every interaction should feel effortless and empowering.
|
||||||
<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
|
|
||||||
|
|
||||||
[SECTION_2_CONTENT]
|
### III. Hook-Driven Extensibility
|
||||||
<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
|
|
||||||
|
|
||||||
## [SECTION_3_NAME]
|
Extensibility MUST be achieved through well-defined hooks:
|
||||||
<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
|
- 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]
|
**Rationale**: Hooks are the foundation of Claude Code's extensibility. Well-designed hooks enable users to customize behavior without modifying core code.
|
||||||
<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
|
|
||||||
|
### 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
|
## Governance
|
||||||
<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
|
|
||||||
|
|
||||||
[GOVERNANCE_RULES]
|
### Constitutional Authority
|
||||||
<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
|
|
||||||
|
|
||||||
**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
|
This constitution supersedes all other project practices and guidelines. When conflicts arise between this constitution and other documentation, the constitution takes precedence.
|
||||||
<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
|
|
||||||
|
### 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.*
|
*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
|
## Project Structure
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user