From 76d57d896baa3e8dfa73f16ea7ff491afa76e54d Mon Sep 17 00:00:00 2001 From: pukpuk Date: Thu, 9 Oct 2025 12:53:33 +0800 Subject: [PATCH] init bmad --- .gitignore | 38 +++++ .mcp.json | 21 +++ .specify/memory/constitution.md | 219 +++++++++++++++++++++++----- .specify/templates/plan-template.md | 40 ++++- 4 files changed, 282 insertions(+), 36 deletions(-) create mode 100644 .gitignore create mode 100644 .mcp.json diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e33c32b --- /dev/null +++ b/.gitignore @@ -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/ diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..5c7dffb --- /dev/null +++ b/.mcp.json @@ -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": {} + } + } +} \ No newline at end of file diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index 1ed8d77..2430add 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -1,50 +1,199 @@ -# [PROJECT_NAME] Constitution - + + +# Claude Code Tools Constitution ## Core Principles -### [PRINCIPLE_1_NAME] - -[PRINCIPLE_1_DESCRIPTION] - +### I. Tool-First Architecture -### [PRINCIPLE_2_NAME] - -[PRINCIPLE_2_DESCRIPTION] - +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] - -[PRINCIPLE_3_DESCRIPTION] - +**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] - -[PRINCIPLE_4_DESCRIPTION] - +### II. Developer Experience (DX) Priority -### [PRINCIPLE_5_NAME] - -[PRINCIPLE_5_DESCRIPTION] - +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] - +**Rationale**: Claude Code users are developers. Poor DX creates friction and reduces adoption. Every interaction should feel effortless and empowering. -[SECTION_2_CONTENT] - +### III. Hook-Driven Extensibility -## [SECTION_3_NAME] - +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] - +**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 - -[GOVERNANCE_RULES] - +### Constitutional Authority -**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE] - \ No newline at end of file +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 diff --git a/.specify/templates/plan-template.md b/.specify/templates/plan-template.md index 70fa8f9..e543c24 100644 --- a/.specify/templates/plan-template.md +++ b/.specify/templates/plan-template.md @@ -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