@rrgarciach/flow-spec 0.1.0

package/template/ai-specs/flow-spec-instructions.md

@@ -0,0 +1,389 @@
+# Flow Spec: a spec-driven toolkit for AI coding agents
+
+<!-- TODO: add a project logo/banner here -->
+
+Bring OpenSpec's spec-driven discipline into any codebase and hand your coding agent a full toolkit to work with.
+
+This repository bundles a curated set of engineering rules, technical standards, and AI agent configuration meant to run consistently across several coding copilots. Drop the whole structure into a project and it starts producing AI-assisted work that follows the same conventions every time.
+
+Pairs naturally with spec-driven frameworks such as [OpenSpec](https://github.com/Fission-AI/OpenSpec).
+
+## 📁 Repository Structure
+
+```
+.
+├── docs/                        # Development standards and specifications
+│   ├── base-standards.md        # Core development rules (single source of truth)
+│   ├── backend-standards.md
+│   ├── frontend-standards.md
+│   ├── documentation-standards.md
+│   ├── api-spec.yml             # OpenAPI specification
+│   ├── data-model.md            # Database and domain models
+│   ├── development_guide.md
+├── ai-specs/
+│   ├── agents/                  # Agent role definitions (backend, frontend, analyst, etc.)
+│   └── skills/                  # Reusable skill prompts/workflows
+│
+├── AGENTS.md                    # Generic agent configuration
+├── CLAUDE.md                    # Claude-specific configuration
+├── codex.md                     # GitHub Copilot/Codex configuration
+└── GEMINI.md                    # Gemini-specific configuration
+```
+
+## 🤖 Multi-Copilot Support
+
+Rather than maintaining separate rule sets per tool, this repo relies on **symlinks and file-naming conventions** so multiple AI copilots can share one source of truth:
+
+- **`AGENTS.md`** → generic instructions most copilots pick up
+- **`CLAUDE.md`** → the file Claude Code / Cursor look for
+- **`codex.md`** → the file GitHub Copilot / Codex look for
+- **`GEMINI.md`** → the file Google Gemini looks for
+
+Every one of these is a symlink pointing at `docs/base-standards.md`, so editing the rules once updates every tool at the same time.
+
+### Why This Approach?
+
+✅ **One source of truth**: rules live only in `base-standards.md`
+✅ **No per-tool duplication**: each copilot just finds its expected filename
+✅ **Works out of the box**: drop it into a project and it's already wired up
+✅ **Cheap to maintain**: one edit propagates to every copilot
+✅ **Fully portable**: reuse the same structure across any number of projects
+
+## 🚀 Quick Start
+
+### 1) Install and Initialize OpenSpec
+
+This setup is designed to sit on top of OpenSpec, so install it first.
+
+Requirement from OpenSpec's own docs:
+
+- Node.js `20.19.0` or higher
+
+Install the CLI globally:
+
+```bash
+npm install -g @fission-ai/openspec@latest
+```
+
+Then, from your project root:
+
+```bash
+cd your-project
+openspec init
+```
+
+### 2) Bring Flow Spec Into Your Project
+
+Copy this repo's contents into your project so `docs/` and `ai-specs/` exist before you touch OpenSpec's config:
+
+```bash
+# Clone or copy this repository into your project (`-n`: do not overwrite existing files so you keep project's original README)
+cp -rn flow-spec/* your-project/
+```
+
+Claude Code users have a second option for this step:
+
+- Install the Claude plugin and let it perform the import for you.
+- Note this only changes **how the files get copied in** — it won't install OpenSpec, touch its config, or fill in `docs/` for you.
+
+Or just run the installer directly:
+
+```bash
+npx @rrgarciach/flow-spec
+```
+
+It writes every template file into place and rebuilds the symlink layout automatically. Re-running it is harmless — it never clobbers files that already exist.
+
+### 3) Fill In `docs/` With Your Own Context (Mandatory)
+
+Don't skip this. Without it, your AI copilot keeps reasoning from placeholder context instead of your actual project.
+
+Rewrite the files under `docs/` so they describe your real stack, architecture, domain vocabulary, API contracts, and data model.
+
+See the [Customization](#-customization) section below for a ready-to-use prompt.
+
+### 4) Wire OpenSpec's Config to Your `docs/` and `ai-specs/`
+
+Once `openspec init` has run and the repo has been copied in, point your project's `config.yml` at the technical context living in `docs/`.
+
+A prompt you can hand your copilot to do this automatically:
+
+```text
+Update my openspec config.yml context to reference this repository's docs and ai-specs structure.
+
+Requirements:
+- Use docs/base-standards.md as the single source of truth.
+- Include docs/backend-standards.md, docs/frontend-standards.md, docs/documentation-standards.md.
+- Include docs/api-spec.yml and docs/data-model.md.
+- Tell the agent to adopt ai-specs/agents/backend-developer.md for backend work and ai-specs/agents/frontend-developer.md for frontend work.
+- Mention ai-specs/skills as workflow guidance.
+- Keep all paths relative to the project root.
+```
+
+Example (`config.yml`):
+
+```yml
+context: |
+  Tech stack: TODO - your languages, frameworks, and key infrastructure (e.g. AWS)
+  Architecture: TODO - your architectural style (e.g. layered, hexagonal, serverless)
+  We use conventional commits
+  Domain: TODO - one line describing what this project does and for whom
+  All code, comments, documentation, and technical artifacts must be in English
+
+  Project specs (single source of truth): All artifact creation and implementation MUST follow the project's technical context in ai-specs/. Read and apply these when creating or implementing:
+  - docs/base-standards.md — core principles, TDD, language standards, links to backend/frontend/docs standards
+  - docs/backend-standards.md — API, database, testing, security (backend changes)
+  - docs/frontend-standards.md — React, UI/UX (frontend changes)
+  - docs/api-spec.yml — API contracts and endpoint definitions
+  - docs/data-model.md — domain and data model
+  - docs/documentation-standards.md — docs structure and maintenance
+  For implementation: adopt the relevant agent from ai-specs/agents/ (e.g. backend-developer.md for backend, frontend-developer.md for frontend). Use ai-specs/skills/ for workflow guidance when applicable.
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+rules:
+  # Global: apply ai-specs when creating any artifact
+  _global:
+    - Before creating any artifact, read and apply docs/base-standards.md
+    - For backend-related artifacts, read docs/backend-standards.md and adopt guidelines from ai-specs/agents/backend-developer.md
+    - For frontend-related artifacts, read docs/frontend-standards.md and adopt guidelines from ai-specs/agents/frontend-developer.md
+    - Use docs/api-spec.yml and docs/data-model.md for API and data consistency in specs and tasks
+```
+
+## ✅ Verify Configuration (Required)
+
+Once the steps above are done, check that your copilot is actually picking things up.
+
+It should automatically resolve:
+
+- **Claude/Cursor**: `CLAUDE.md` → `docs/base-standards.md`
+- **GitHub Copilot**: `codex.md` → `docs/base-standards.md`
+- **Gemini**: `GEMINI.md` → `docs/base-standards.md`
+
+No manual wiring needed beyond what's already in place.
+
+## 💡 Usage: Official OpenSpec Workflow
+
+This repo leans on OpenSpec's own commands to drive the day-to-day loop:
+
+1. **`/enrich-us`** (optional): turn a rough idea or ticket into a well-specified user story
+2. **`/new`**: start a new OpenSpec change (currently just an alias for `/ff`)
+3. **`/ff`**: generate every required OpenSpec artifact (proposal, tasks, etc.)
+   - `/new` followed by `/ff` is functionally the same as the newer `/propose` command
+4. **`/apply`**: work through the tasks one at a time
+5. **`/verify`**: check the implementation against what the change actually specified
+6. **`/adversarial-review`**: an independent, red-team-style pass before anything gets archived
+7. **`/archive`**: close out the finished change
+8. **`/commit`**: produce a focused commit and handle the Pull Request once verification is done
+
+Workflow reference:
+
+```mermaid
+flowchart TB
+    subgraph TOP[" "]
+        direction LR
+        US["User Story"] -->|"/enrich-us"| RUS["Refined User Story"] -->|"/new + /ff"| PA["Proposal Artifacts"]
+    end
+
+    subgraph MID["/apply output"]
+        direction TB
+        BR["Branch"] --> TE["Tests"] --> DOC["Documentation"] --> CODE["Code"] --> TR["Testing Report"] --> PU["Proposal Update"]
+    end
+
+    subgraph BOTTOM[" "]
+        direction LR
+        READY["Feature Ready"] -->|"/archive + /commit"| PRFEAT["Feature for PR"] --> PUB["Feature Published"]
+    end
+
+    PA -->|"/apply"| BR
+    PU -.->|"/verify + /adversarial-review: implement changes"| BR
+    PU -->|"/verify + /adversarial-review: passes"| READY
+```
+
+### Optional: MCP Integrations (monday.com + Playwright)
+
+A couple of MCP servers make parts of this workflow smoother. Both are optional — skip either one, or swap in whatever equivalent tool you already use.
+
+- **monday.com MCP (used by `/enrich-us`)**: lets the agent pull item details straight from a board instead of you copy-pasting them in. Keep a custom text column on the board holding a readable key (e.g. `PROJ-123`) so items can be looked up by that value rather than the internal numeric item id.
+- **Playwright MCP (for E2E checks)**: gives the agent a real browser to drive when validating user-facing flows.
+
+To set these up:
+
+- **Cursor**: register the MCP servers under Cursor's settings, then supply the credentials each one needs (e.g. a monday.com API token).
+- **Other tools/IDEs**: follow that tool's own MCP setup docs to add the monday.com and Playwright servers.
+
+Not using monday.com, or don't want automated E2E checks? Just adjust the affected skills and the rest of the OpenSpec flow keeps working as-is.
+
+### Example: End-to-End Flow
+
+A typical run through the commands, in order:
+
+It's worth spinning up a dedicated worktree first (the `using-git-worktrees` skill handles this) and tearing it down once you're done.
+
+```bash
+/enrich-us SCRUM-10
+/ff SCRUM-10
+/apply SCRUM-10
+/verify SCRUM-10
+/adversarial-review SCRUM-10
+/archive SCRUM-10
+/commit
+```
+
+OpenSpec's own directories track every artifact produced along the way, including the testing reports generated during the run.
+
+### Useful Skills
+
+Skills are defined once under `ai-specs/skills/` and exposed to every copilot via relative symlinks in `.claude/skills/` and `.cursor/skills/`. Whichever agent you're running, it picks up a skill automatically once a request matches that skill's description (see `AGENTS.md` §4). The ones you'll reach for most often are **`enrich-us`**, **`using-git-worktrees`**, **`writing-skills`**, and **`code-auditing`**:
+
+- **`enrich-us`** — Turns a thin user story (pulled from monday.com, or just an idea typed in chat) into something implementation-ready: acceptance criteria, technical detail, edge cases. Run this **before** planning so the team and the agent start from the same understanding of scope.
+- **`using-git-worktrees`** — Spins up an isolated workspace before you start a feature or run a plan: safe creation, baseline checks, copying over local Claude settings, and a full teardown once the work is merged.
+- **`writing-skills`** — Guides you through authoring or refactoring a skill with TDD-style validation before it ships. Reach for this whenever you're touching `ai-specs/skills/`.
+- **`code-auditing`** — Walks a codebase through a 6-phase quality pass (security, performance, type safety, dead code, library health) and ends with a ranked action list. Good fit for pre-release checks or a technical-debt sweep.
+
+The repo also ships `commit`, `explain`, `meta-prompt`, and `update-docs` as active skills — check each `ai-specs/skills/<name>/SKILL.md` for specifics.
+
+## 📖 Core Development Rules
+
+Everything here flows from the principles in `docs/base-standards.md`:
+
+### Key Principles
+
+1. **Small Tasks, One at a Time**: move in small, reviewable steps — never several stages ahead
+2. **Test-Driven Development (TDD)**: red before green, every time
+3. **Type Safety**: no untyped code paths (TypeScript throughout)
+4. **Clear Naming**: names should explain themselves
+5. **English Only**: code, comments, docs, and commit messages, no exceptions
+6. **90%+ Test Coverage**: across every layer, not just the happy path
+7. **Incremental Changes**: keep diffs small and easy to review
+
+### Specific Standards
+
+- **Backend Standards**: `docs/backend-standards.md`
+  - API development patterns
+  - Database best practices
+  - Security guidelines
+  - Testing requirements
+- **Frontend Standards**: `docs/frontend-standards.md`
+  - React component patterns
+  - UI/UX guidelines
+  - State management
+  - Component testing
+- **Documentation Standards**: `docs/documentation-standards.md`
+  - Technical documentation structure
+  - API documentation (OpenAPI)
+  - Code documentation
+  - Maintenance guidelines
+
+## 🎯 Benefits
+
+### For Developers
+
+- ✅ **Consistent Code Quality**: the agent applies the same rules run after run
+- ✅ **Comprehensive Testing**: 90%+ coverage across layers, without chasing it manually
+- ✅ **Complete Documentation**: API specs stay current as part of the flow
+- ✅ **Faster Onboarding**: newcomers read the same rules the agent already follows
+- ✅ **Reduced Review Time**: output already matches established patterns
+
+### For Teams
+
+- ✅ **Copilot Flexibility**: everyone keeps using the AI tool they prefer
+- ✅ **Knowledge Preservation**: standards live in files, not in someone's head
+- ✅ **Quality Consistency**: the same bar applies no matter who — or what — wrote the code
+- ✅ **Easier Code Reviews**: expectations are explicit going in
+- ✅ **Scalable Practices**: the rules scale with headcount, the docs don't need to
+
+### For Projects
+
+- ✅ **Maintainable Codebase**: clean architecture, clear layering
+- ✅ **Production-Ready Code**: TDD, error handling, and validation baked in from the start
+- ✅ **Living Documentation**: specs and data models stay in sync with reality
+- ✅ **Faster Feature Development**: the agent can implement autonomously from a plan
+- ✅ **Lower Technical Debt**: good practices are the default, not an afterthought
+
+## 🔧 Customization
+
+### Adapting to Your Project
+
+1. **Rewrite the technical context**: go through everything under `docs/` and replace the principles, conventions, business rules, and reference material with your project's own:
+  - backend/frontend/testing/documentation standards
+  - installation guide
+  - data model
+  - API docs
+  - ...
+2. **Adjust the agent roles in `ai-specs/agents`**: match them to how your team actually splits responsibilities
+3. **Grow the skill library in `ai-specs/skills`**: capture proven prompts and workflows as reusable skills
+4. **Wire up external resources**: connect project docs or ticket systems through MCPs
+5. **Preserve the symlink layout**: keep `.claude` and `.cursor` pointing at `ai-specs/agents` and `ai-specs/skills` via relative symlinks so nothing drifts out of sync
+
+### Prompt Example: Adapt Technical Context
+
+A prompt you can hand your copilot to rewrite `docs/` while keeping the same layout:
+
+```text
+Following the same base structure already present in docs/, update all technical context documents according to this project's specifics.
+
+Requirements:
+- Keep the same document set and file names in docs/.
+- Replace generic content with this project's real stack, architecture patterns, coding conventions, and domain terminology.
+- Update backend, frontend, and documentation standards to reflect actual practices used by this team.
+- Update docs/api-spec.yml and docs/data-model.md so they match the real endpoints and entities of this project.
+- Ensure all references are internally consistent and aligned across docs/.
+- Keep everything in English and make guidance implementation-ready for AI agents.
+```
+
+### Maintaining Standards
+
+- **Single Source of Truth**: `base-standards.md` gets updated first, always
+- **Version Control**: treat standards changes like any other code change
+- **Team Review**: run changes to the standards through review, same as a PR
+- **Documentation**: keep the examples honest with what's actually implemented
+- **Symlink Integrity**: renaming or moving a file means checking every symlink that points at it
+- **Canonical Placement**: `ai-specs` stays the canonical source; `.claude`/`.cursor` only ever hold symlinks into it
+
+## 📚 Technical context
+
+### `docs/` Templates (Fill These In)
+
+The files below ship as **empty skeletons**: the section headers show what to cover, but every `_TODO_` needs your project's real content before an agent can use it as context:
+
+- **API Specification**: `docs/api-spec.yml` (OpenAPI 3.0 format)
+  - *Document your actual endpoints here instead*
+- **Data Models**: `docs/data-model.md` (Database schemas, domain models)
+  - *Describe your real database structure and domain entities*
+- **Development Guide**: `docs/development_guide.md` (Setup, workflows)
+  - *Write the setup steps that match your actual tech stack*
+
+## 🤝 Contributing
+
+When changing the standards themselves:
+
+1. Update `base-standards.md` first — it's the single source of truth
+2. Confirm the change still works across the AI copilots you support
+3. Refresh any generated examples under `changes/` that are now out of date
+4. Call out breaking changes explicitly
+5. Hold the standards documents to the same bar they set for everything else
+
+## 📄 License
+
+Copyright (c) 2026 Ruy Garcia
+Licensed under the MIT License
+
+---
+
+## 🙏 Acknowledgements
+
+Several workflow and skill patterns here draw on the Superpowers framework, particularly:
+
+- `using-git-worktrees`
+- `writing-skills`
+
+Superpowers project: [obra/superpowers](https://github.com/obra/superpowers/tree/main)
+
+Additional attribution:
+
+- `code-auditing` skill: adapted from [jeffrigby/somepulp-agents](https://github.com/jeffrigby/somepulp-agents/tree/main)
+
+**Made with 🤖 by Flow Spec**
+
+Questions, issues, or suggestions? Open an issue on the Flow Spec repository.

package/template/ai-specs/scripts/code_review.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# code_review.sh - Basic code review report
+
+set -euo pipefail
+
+echo "Starting code review..."
+
+if ! command -v agent >/dev/null 2>&1; then
+  echo "Error: 'agent' command not found in PATH."
+  exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TIMESTAMP="$(date +%Y%m%d_%H%M%S)"
+OUTPUT_FILE="${SCRIPT_DIR}/review_${TIMESTAMP}.txt"
+
+if agent -p --output-format text \
+  "Review the recent code changes and provide feedback on:
+  - Code quality and readability
+  - Possible bugs or issues
+  - Security considerations
+  - Best-practices compliance
+
+  Provide specific improvement suggestions." > "${OUTPUT_FILE}"; then
+  if [[ -s "${OUTPUT_FILE}" ]]; then
+    echo "Code review completed successfully."
+    echo "Review saved to: ${OUTPUT_FILE}"
+  else
+    echo "Code review failed: output file is empty."
+    exit 1
+  fi
+else
+  echo "Code review failed while running 'agent'."
+  exit 1
+fi

package/template/ai-specs/skills/code-auditing/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: code-auditing
+description: Task-focused project skill.
+version: 1.0.0
+---
+# Code Auditing Skill
+
+Comprehensive methodology for systematic code quality audits.
+
+## When to Use
+
+- Comprehensive code quality audits
+- Security vulnerability assessments
+- Technical debt identification
+- Pre-release code reviews
+- Best practices verification
+- Library and dependency audits
+
+## Audit Phases
+
+### Phase 0: Pre-Analysis Setup
+1. Check for project configuration files (package.json, tsconfig.json, etc.)
+2. Identify tech stack and main libraries
+3. Check for linting/formatting configs
+4. Run existing linting/testing commands as baseline
+5. Load documentation for identified core libraries
+
+### Phase 1: Discovery
+1. Find all code files by type
+2. Create tracking list for each file
+3. Group files by module/feature for contextual analysis
+
+### Phase 2: File-by-File Analysis
+For each file, analyze for:
+- Dead code (unused functions, variables, imports)
+- Code smells and anti-patterns
+- Custom implementations that could use established libraries
+- Security vulnerabilities
+- Performance issues
+- Outdated patterns or deprecated APIs
+- Missing error handling
+- Overly complex functions
+- Duplicate code
+
+### Phase 3: Best Practices Verification
+For every library and framework:
+1. Retrieve official documentation
+2. Compare implementation against official patterns
+3. Identify deviations from recommendations
+4. Note outdated usage patterns
+5. Flag discouraged anti-patterns
+
+### Phase 4: Pattern Detection
+Look for recurring issues:
+- Common anti-patterns across files
+- Duplicated logic that could be abstracted
+- Inconsistent coding styles
+- Missing error handling patterns
+
+### Phase 5: Library Recommendations
+For custom implementations:
+1. Check if current libraries provide the functionality
+2. Search for mature ecosystem packages
+3. Verify library health (commits, issues, activity)
+4. Check compatibility with project setup
+
+### Phase 6: Comprehensive Report
+Generate detailed report with:
+- Executive summary
+- Critical issues requiring immediate attention
+- File-by-file findings
+- Prioritized action plan
+- Effort estimates
+- Library recommendations
+
+## Issue Priority Levels
+
+- **Critical** - Security vulnerabilities, broken functionality
+- **High Priority** - Performance bottlenecks, unmaintainable code
+- **Medium Priority** - Code quality, best practices deviations
+- **Low Priority** - Style, minor improvements
+- **Quick Wins** - Less than 30 minutes to fix
+
+## Analysis Categories
+
+### Security
+- Hardcoded secrets
+- SQL injection risks
+- XSS vulnerabilities
+- Missing input validation
+- Exposed sensitive data
+
+### Performance
+- Inefficient algorithms
+- Blocking operations
+- Memory leaks
+- Missing caching opportunities
+- N+1 query patterns
+
+### TypeScript/Type Safety
+- Missing type annotations
+- Use of `any` type
+- Custom types duplicating official types
+- Missing @types packages
+
+### Async/Promise Issues
+- Missing await keywords
+- Unhandled promise rejections
+- Callback hell
+
+### Dead Code
+- Unused imports and exports
+- Unused functions, classes, and methods
+- Unused variables and types
+- Unreachable code blocks
+- Unused files (not imported anywhere)
+- Unused dependencies
+
+**Tools:**
+- JavaScript/TypeScript: `npx knip --reporter json`
+- Python: `deadcode . --dry`
+
+**Important:** Always verify tool findings before reporting. Check for:
+- Dynamic imports (`import(variable)`)
+- Framework patterns (React components, decorators)
+- Re-exports for public API
+- Entry points (CLI scripts, serverless handlers)
+
+## Resources
+
+See the reference documents for complete methodologies:
+
+- `references/audit-methodology.md` - Full 6-phase audit process with detailed checklists
+- `references/dead-code-methodology.md` - Dead code detection tools, verification, and cleanup workflows
+
+## Quick Reference
+
+### Before Starting
+- [ ] Read project configuration files
+- [ ] Identify tech stack and libraries
+- [ ] Run existing linters as baseline
+- [ ] Create file tracking list
+
+### During Audit
+- [ ] Mark files as in-progress
+- [ ] Analyze each category systematically
+- [ ] Note specific line numbers
+- [ ] Document before/after examples
+- [ ] Mark files as completed
+
+### After Audit
+- [ ] Categorize all findings by priority
+- [ ] Generate comprehensive report
+- [ ] Save report to project root
+- [ ] Provide brief console summary