# {{PROJECT_NAME}} {{PROJECT_DESCRIPTION}} > {{VISION_STATEMENT}} --- ## ⚡ For AI Developers & Assistants **Before starting work, read these files:** 1. **`.ai-context.yml`** - See this file for: - Complete context loading sequence (ai.context_sequence) - AI decision tree for routing - File purposes and cross-references - Classification zones - Deployment mode configurations 2. **`.cursorrules.md`** - Team workflow rules: - Development standards and constraints - Definition of Done - Template vs feature modes 3. **This README** - Public documentation overview 4. **`memory-bank/activeContext.md (or legacy context/vision.md)`** - Product vision & current phase 5. **`memory-bank/releases/current-release.md`** - Current scope **Key Reference:** See `.ai-context.yml {#ai-context-loading-order}` for complete reading order (priority 1-6) **Time to read full context:** ~15-20 minutes --- ## Quick Start ### Installation ```bash # One-command setup bash <(curl -s https://raw.githubusercontent.com/your-org/{{REPO_NAME}}/main/setup.sh) # Or manually git clone https://github.com/your-org/{{REPO_NAME}}.git cd {{REPO_NAME}} npm install ``` ### First Steps 1. **Read the vision:** `cat memory-bank/activeContext.md (or legacy context/vision.md)` 2. **Review current release:** `cat memory-bank/releases/current-release.md` 3. **Use Cursor commands:** ```bash # In Cursor AI chat: @mention /analyze-repo # Audit the codebase @mention /create-epic # Plan a feature @mention /create-release # Generate release docs ``` --- ## Repository Structure This project uses [Roadcrew](https://github.com/tailwind-ai/roadcrew) for release management and AI-powered automation. ``` {{REPO_NAME}}/ ├── .ai-context.yml ← Project configuration (entry point) ├── .cursorrules.md ← Team workflow rules │ ├── context/ ← Product specifications │ ├── vision.md ← Product vision & strategy │ ├── tech-stack.md ← Technology stack (auto-generated) │ ├── memory-bank/ ← Strategic docs (hierarchical) │ ├── prds/ ← Product requirements documents │ ├── brds/ ← Business requirements documents │ ├── specs/ ← Technical specifications │ └── narratives/ ← Implementation guides │ ├── memory-bank/releases/ ← Release tracking │ ├── current-release.md ← What we're working on now │ ├── future-releases.md ← Planned releases │ └── past-releases.md ← Historical releases & retrospectives │ ├── .roadcrew/ ← Roadcrew templates & utilities │ ├── commands/ ← AI Cursor commands │ ├── templates/ ← Document templates │ │ ├── memory-bank/ ← Strategic document templates │ │ │ ├── releases/ ← Release templates │ │ │ └── requirements/ ← Requirement templates (BRDs, PRDs, Specs) │ │ └── (other templates) │ └── dist/ ← Compiled utility scripts │ ├── config/ ← Configuration files │ ├── tech-stack.md ← Technology stack (auto-generated) │ └── reports/ ← Analysis reports │ ├── src/ ← Source code ├── tests/ ← Test files └── README.md ← This file ``` --- ## Key Workflows ### 🚀 Planning a Release ```bash # 1. Create an epic in GitHub @mention /create-epic # 2. Define requirements @mention /create-prd # 3. Generate technical spec @mention /create-spec # 4. Plan release timeline @mention /scope-release ``` ### 📝 Documenting Features All documentation uses templates in `context/`: - **BRD** (`memory-bank/requirements/brds/brd.template.md`) - Business requirements - **PRD** (`memory-bank/requirements/prds/prd.template.md`) - What are we building? - **Spec** (`memory-bank/requirements/specs/spec.template.md`) - How will we build it? - **Epic** (`epic.template.md`) - Track progress in GitHub **Reference:** See [.roadcrew/templates/](../.roadcrew/templates/) for all available templates. ### 🎯 Tracking Progress **Current work:** `memory-bank/releases/current-release.md` (See `.roadcrew/templates/memory-bank/releases/current-release.template.md`) - What are we building this release? - What's our target date? - What's our success criteria? **Upcoming:** `memory-bank/releases/future-releases.md` (See `.roadcrew/templates/memory-bank/releases/future-releases.template.md`) - Planned features and releases - Roadmap visibility **Historical:** `memory-bank/releases/past-releases.md` (See `.roadcrew/templates/memory-bank/releases/past-releases.template.md`) - What we shipped and when - Retrospectives and lessons learned ### 👥 Team Collaboration **Workflow rules:** `.cursorrules.md` - Definition of Done for all work - Communication standards - Code review process **Tech stack:** `memory-bank/techContext.md` - Languages, frameworks, databases - Auto-generated by `/analyze-repo` --- ## Features {{#FEATURES}} - {{FEATURE_DESCRIPTION}} {{/FEATURES}} --- ## Requirements - **Node.js** {{NODE_VERSION}} - **npm** {{NPM_VERSION}} - **Git** (for version control) - **Cursor IDE** (optional, for AI-powered commands) {{#ADDITIONAL_REQUIREMENTS}} - {{REQUIREMENT}} {{/ADDITIONAL_REQUIREMENTS}} --- ## Installation & Setup ### Prerequisites ```bash node --version # Requires {{NODE_VERSION}}+ npm --version # Requires {{NPM_VERSION}}+ ``` ### Development Setup ```bash # 1. Clone repository git clone https://github.com/your-org/{{REPO_NAME}}.git cd {{REPO_NAME}} # 2. Install dependencies npm install # 3. Configure environment cp .env.example .env # Edit .env with your configuration # 4. Verify installation npm run build npm test ``` ### Running the Project ```bash # Development npm run dev # Production build npm run build npm start # Run tests npm test # Run tests in watch mode npm test -- --watch ``` --- ## Development Workflow ### Creating a New Feature 1. **Create an epic** in GitHub (use `/create-epic` command) 2. **Define requirements** in `memory-bank/requirements/prds/` 3. **Create technical spec** in `memory-bank/requirements/specs/` 4. **Create child issues** with `/scope-release` 5. **Implement** with test-first approach 6. **Submit PR** with reference to epic/issue ### Code Standards {{#CODE_STANDARDS}} - {{STANDARD}} {{/CODE_STANDARDS}} **Definition of Done:** See `.cursorrules.md` for complete checklist ### Testing ```bash # Run all tests npm test # Run specific test file npm test -- path/to/test.ts # Generate coverage npm test -- --coverage ``` --- ## Architecture {{ARCHITECTURE_OVERVIEW}} ### Key Components {{#COMPONENTS}} - **{{COMPONENT_NAME}}** - {{COMPONENT_DESCRIPTION}} {{/COMPONENTS}} ### Tech Stack **Language:** {{PRIMARY_LANGUAGE}} **Runtime:** {{RUNTIME}} **Package Manager:** {{PACKAGE_MANAGER}} **Testing:** {{TEST_FRAMEWORK}} **Database:** {{DATABASE}} *Auto-generated by `/analyze-repo` - see `memory-bank/techContext.md` for full details* --- ## Deployment ### Staging ```bash npm run build:staging npm run deploy:staging ``` ### Production ```bash npm run build:production npm run deploy:production ``` **Deployment method:** {{DEPLOYMENT_METHOD}} --- ## Contributing We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. **Quick start for contributors:** 1. Fork the repository 2. Create a feature branch: `git checkout -b feature/my-feature` 3. Make changes following `.cursorrules.md` 4. Add tests for new functionality 5. Submit a pull request **See also:** [CONTRIBUTING.md](CONTRIBUTING.md) for full contribution guidelines --- ## Release Process **Current Release:** See `memory-bank/releases/current-release.md` ### Release Checklist - [ ] All features merged to main - [ ] All tests passing - [ ] Documentation updated - [ ] Version bumped (using semantic versioning) - [ ] Release notes generated - [ ] Deployed to staging - [ ] Verified in staging - [ ] Deployed to production - [ ] Announced to team/community See [CHANGELOG.md](CHANGELOG.md) for version history. --- ## Troubleshooting ### Common Issues **Issue:** Build fails ```bash # Solution: Clear cache and reinstall rm -rf node_modules package-lock.json npm install npm run build ``` **Issue:** Tests failing ```bash # Solution: Update snapshots npm test -- --updateSnapshot ``` **Issue:** Environment variables not loaded ```bash # Solution: Verify .env file exists and is populated cp .env.example .env # Edit .env with your values ``` ### Getting Help - 📖 Check [docs/](docs/) for detailed guides - 🐛 Report bugs on [GitHub Issues](https://github.com/your-org/{{REPO_NAME}}/issues) - 💬 Ask questions in [GitHub Discussions](https://github.com/your-org/{{REPO_NAME}}/discussions) - 📚 Review [context/](context/) for product/technical documentation --- ## Performance & Metrics **Current KPIs:** {{#METRICS}} - {{METRIC_NAME}}: {{METRIC_VALUE}} {{/METRICS}} **Success Criteria:** See `memory-bank/releases/current-release.md` for release-specific targets --- ## Security - **Vulnerability Reporting:** See [SECURITY.md](SECURITY.md) - **Dependency Management:** `npm audit` run on every PR - **Code Review:** All PRs require review before merge {{#SECURITY_INFO}} - {{SECURITY_DETAIL}} {{/SECURITY_INFO}} --- ## License This project is licensed under {{LICENSE_TYPE}} - see [LICENSE](LICENSE) file for details. {{#COMMERCIAL_LICENSE}} Commercial licensing available - see [LICENSE-COMMERCIAL](LICENSE-COMMERCIAL) {{/COMMERCIAL_LICENSE}} --- ## Powered by Roadcrew This project uses [Roadcrew](https://github.com/tailwind-ai/roadcrew) for: - 📋 Release management and planning - 📝 Specification and documentation generation - 🚀 AI-powered automation with Cursor - 🎯 Theory of Constraints (TOC) resource optimization **Learn more:** [Roadcrew Documentation](https://github.com/tailwind-ai/roadcrew) --- ## Project Links - 🏠 **Website:** {{WEBSITE_URL}} - 📖 **Documentation:** {{DOCS_URL}} - 🐛 **Issues:** [GitHub Issues](https://github.com/your-org/{{REPO_NAME}}/issues) - 💬 **Discussions:** [GitHub Discussions](https://github.com/your-org/{{REPO_NAME}}/discussions) - 📝 **Changelog:** [CHANGELOG.md](CHANGELOG.md) --- ## Authors {{#AUTHORS}} - {{AUTHOR_NAME}} ({{AUTHOR_ROLE}}) {{/AUTHORS}} --- **Last Updated:** {{LAST_UPDATED}} **Version:** {{CURRENT_VERSION}} --- ## 🤖 For AI Systems **Metadata for AI Context Loading:** See `.ai-context.yml` for authoritative metadata: - `ai.context_sequence` - Priority-ordered reading list (1-6) - `ai.ai_decision_tree` - Scenario routing (templates vs features vs support) - `classification.zones` - Work classification system (1-10 scale) - `constraints_registry` - Constraint sets by scenario - `phase_definitions` - Implications by phase (mvp/beta/ga) **AI Workflow Routing:** ```yaml IF working in templates/ → Read: .ai-context.yml {#template-development-mode} → Use: constraints_registry.template_mode → Reference: .cursorrules.md {#template-development-mode} ELSE IF working on source code → Read: .ai-context.yml {#feature-development-mode} → Use: constraints_registry.feature_mode → Reference: .cursorrules.md {#feature-development-mode} ELSE IF customer support → Use: constraints_registry.support_mode → Reference: README.md {#contributing} ``` **Quick Lookup:** - Classification zones: `.ai-context.yml {#classification}` - Deployment modes: `.ai-context.yml {#deployment-modes}` - Current phase: `.ai-context.yml current_state.phase` - Phase implications: `.ai-context.yml {#phase-definitions}` - Validation rules: `.ai-context.yml {#validation}` --- Made with ❤️ using [Roadcrew](https://github.com/tailwind-ai/roadcrew)