codecruise 0.1.0

package/config/rules/scope-detection.md

@@ -0,0 +1,213 @@
+# Scope Detection Rules
+
+When `/run` receives a new intent (quoted string), determine the appropriate ceremony level.
+
+## Ceremony Levels
+
+| Level | Spec | Plan | Human Gates | Use Case |
+|-------|------|------|-------------|----------|
+| **quick** | No | No | 0 | Trivial tasks, fixes |
+| **medium** | Lightweight | Auto | 1 (spec) | Features, integrations |
+| **full** | Detailed | Detailed | 2 (spec + plan) | Systems, major features |
+
+## Detection Algorithm
+
+```
+INPUT: user_intent (string)
+
+1. KEYWORD ANALYSIS
+   - Extract key terms from intent
+   - Match against complexity indicators
+
+2. SCOPE ESTIMATION
+   - Estimate files to be touched
+   - Estimate time to complete
+   - Check for dependencies/integrations
+
+3. DETERMINE CEREMONY
+   - Apply rules below
+   - Return: quick | medium | full
+
+4. USER CAN OVERRIDE
+   - /run "intent" --ceremony full
+   - /run "intent" --quick
+```
+
+## Quick Ceremony Indicators
+
+**Trigger quick when ALL of:**
+- Single file likely (or 1-3 files max)
+- No new dependencies needed
+- No external integrations
+- Estimated time < 15 minutes
+- Simple, well-defined change
+
+**Keyword patterns (case-insensitive):**
+```
+fix|typo|rename|update|change|tweak|adjust
+add .* button|add .* field|add .* prop
+remove|delete .* (unused|old|deprecated)
+move|relocate
+style|css|color|font|margin|padding
+comment|doc(s)?|readme
+log|print|debug
+```
+
+**Examples:**
+```
+/run "fix typo in README"              → quick
+/run "add logout button to navbar"     → quick
+/run "update the primary color"        → quick
+/run "remove unused imports"           → quick
+```
+
+## Medium Ceremony Indicators
+
+**Trigger medium when ANY of:**
+- Multiple files (4-10 estimated)
+- New functionality (not just modification)
+- API endpoint or route
+- Database changes
+- Estimated time 15-60 minutes
+
+**Keyword patterns:**
+```
+add .* (feature|endpoint|api|route|page|component|service)
+implement|create|build .* (basic|simple)?
+integrate .* (with)?
+connect|hook up
+auth|login|logout|session
+form|validation
+crud|list|table|grid
+```
+
+**Examples:**
+```
+/run "add user authentication"         → medium
+/run "create API endpoint for users"   → medium
+/run "implement form validation"       → medium
+/run "add search functionality"        → medium
+```
+
+## Full Ceremony Indicators
+
+**Trigger full when ANY of:**
+- 10+ files estimated
+- Multiple services/modules affected
+- External service integration (Stripe, AWS, etc.)
+- Database schema changes
+- Security-critical functionality
+- Estimated time > 1 hour
+- Keywords indicate system-level work
+
+**Keyword patterns:**
+```
+(build|create|implement) .* system
+(payment|billing|subscription|checkout)
+(oauth|sso|two.?factor|2fa|mfa)
+(migration|schema|database) .* (change|update|redesign)
+refactor .* (architecture|structure|codebase)
+(microservice|service|module) .* (new|add|create)
+(security|encryption|compliance)
+integration with .* (stripe|aws|gcp|azure|twilio|sendgrid)
+```
+
+**Examples:**
+```
+/run "build payment system"            → full
+/run "implement OAuth with Google"     → full
+/run "refactor the authentication architecture" → full
+/run "integrate Stripe for subscriptions" → full
+```
+
+## File Count Heuristics
+
+When analyzing intent, estimate files:
+
+| Pattern | Estimated Files |
+|---------|-----------------|
+| "button", "field", "prop" | 1-2 |
+| "component", "hook" | 2-3 |
+| "endpoint", "route" | 3-5 |
+| "feature", "page" | 4-8 |
+| "service", "module" | 5-10 |
+| "system", "integration" | 10+ |
+
+## Dependency Heuristics
+
+Detect if new dependencies likely needed:
+
+| Intent Contains | Likely Needs |
+|-----------------|--------------|
+| "stripe", "payment" | stripe |
+| "auth", "oauth", "jwt" | auth libraries |
+| "email", "sendgrid" | email service |
+| "upload", "s3" | storage SDK |
+| "chart", "graph", "visualization" | charting library |
+| "form", "validation" | form library |
+| "date", "time", "calendar" | date library |
+
+If dependencies detected → bump to at least medium.
+
+## Override Flags
+
+```bash
+# Force specific ceremony
+/run "add auth" --ceremony full     # Force full even if detected medium
+/run "payment system" --quick       # Force quick (not recommended)
+
+# Shorthand
+/run "add auth" --full
+/run "fix typo" --medium            # Overkill but allowed
+```
+
+## Output on Detection
+
+When ceremony is determined, briefly explain:
+
+```
+Analyzing: "add user authentication"
+
+Detected:
+  - Keywords: auth, user → medium/full indicator
+  - Estimated files: 4-6
+  - Dependencies: likely (jwt/session library)
+  - Integrations: none detected
+
+Ceremony: MEDIUM
+  → Will ask 2-4 clarifying questions
+  → Will generate spec for approval
+  → Then execute with verification
+
+Proceed? [y/n/--full to upgrade]
+```
+
+## Ambiguous Cases
+
+When detection is unclear:
+
+1. **Default to medium** - safer than quick
+2. **Ask user** if truly ambiguous:
+   ```
+   Intent: "update the user system"
+
+   This could be:
+   [1] Quick - minor updates to existing code
+   [2] Medium - new functionality in user module
+   [3] Full - major user system overhaul
+
+   Which best describes your intent? _
+   ```
+
+## Integration with /run
+
+In `run.md`, after receiving quoted intent:
+
+```
+1. Parse intent string
+2. Apply scope-detection rules (this file)
+3. Determine ceremony level
+4. If quick → execute directly
+5. If medium → ask questions → generate spec → execute
+6. If full → ask questions → generate spec → review → generate plan → review → execute
+```

package/config/rules/standards.md

@@ -0,0 +1,127 @@
+# Coding Standards
+
+## Priority Order
+
+```
+Security > Correctness > Clarity > Performance
+```
+
+Always optimize in this order. Never sacrifice security for performance.
+
+## Naming Conventions
+
+### Functions
+- Use verbs: `getUser`, `createOrder`, `validateInput`
+- Async functions: `fetchUser`, `loadData`, `saveSettings`
+- Event handlers: `handleClick`, `onSubmit`, `onChange`
+- Boolean returns: `isValid`, `hasPermission`, `canEdit`
+
+### Variables
+- Descriptive: `userEmail` not `ue`
+- Booleans: `isLoading`, `hasError`, `canSubmit`
+- Collections: plural nouns `users`, `items`, `orders`
+- Constants: `UPPER_SNAKE_CASE`
+
+### Files & Directories
+- Components: `PascalCase.tsx`
+- Utilities: `kebab-case.ts`
+- Tests: `*.test.ts` or `*.spec.ts`
+- Types: `*.types.ts` or inline
+
+## Error Handling
+
+### Never Swallow Errors
+```typescript
+// BAD
+try { doThing() } catch (e) {}
+
+// GOOD
+try {
+  doThing()
+} catch (error) {
+  logger.error('Failed to do thing', { error, context })
+  throw new AppError('THING_FAILED', error)
+}
+```
+
+### Error Messages
+- Include context: what failed, why, what data
+- Use error codes for programmatic handling
+- User-facing messages separate from technical logs
+
+### Boundary Errors
+- Validate at entry points (API routes, form handlers)
+- Trust validated data within boundaries
+- Parse, don't validate (use Zod or similar)
+
+## Comments
+
+### Explain WHY, Not WHAT
+```typescript
+// BAD: Increments counter
+counter++
+
+// GOOD: Compensate for 0-indexed array when displaying to user
+counter++
+```
+
+### Document Non-Obvious
+- Business logic reasoning
+- Performance optimizations
+- Workarounds with issue links
+- Magic numbers
+
+### TODO Format
+```typescript
+// TODO(username): Description - JIRA-123
+// FIXME: Temporary workaround, remove after v2.0
+// HACK: Explain why this hack exists
+```
+
+## Code Organization
+
+### File Length
+- Max ~300 lines per file
+- Split when file serves multiple purposes
+- Extract when logic is reusable
+
+### Function Length
+- Max ~50 lines per function
+- Single responsibility
+- Extract helper functions
+
+### Import Order
+1. Node built-ins
+2. External packages
+3. Internal aliases (@/)
+4. Relative imports
+5. Types (if separate)
+
+## Security Rules
+
+### Never
+- Commit secrets (use env vars)
+- Log sensitive data (PII, tokens, passwords)
+- Trust user input (always validate)
+- Expose stack traces to users
+- Use `eval()` or `new Function()`
+
+### Always
+- Sanitize database inputs
+- Validate file uploads (type, size, content)
+- Use parameterized queries
+- Implement rate limiting
+- Check authorization on every request
+
+## Performance Guidelines
+
+### Measure First
+- Don't optimize without profiling
+- Focus on hot paths
+- Consider user-perceived performance
+
+### Common Wins
+- Lazy load non-critical resources
+- Cache expensive computations
+- Batch database operations
+- Use appropriate data structures

package/config/rules/workflow.md

@@ -0,0 +1,121 @@
+# Workflow Rules
+
+## Work Breakdown Model
+
+```
+PHASE → FEATURE → [SUBFEATURE] → TODO
+```
+
+## TODO Format (YAML Required)
+
+Always use YAML for TODOs. Never use markdown tables.
+
+```yaml
+todos:
+  - id: todo-001
+    description: Create LoginForm component
+    owner: dev
+    status: pending
+    files:
+      - src/components/LoginForm.tsx
+      - src/components/LoginForm.test.tsx
+    criteria:
+      - Form renders email and password inputs
+      - Validation errors display correctly
+    depends_on: []
+```
+
+Valid statuses: `pending`, `in_progress`, `done`, `blocked`, `skipped`
+
+- **Phases**: Major milestones (auth, dashboard, billing)
+- **Features**: Deliverable units within a phase
+- **Subfeatures**: Optional groupings when features are large
+- **TODOs**: Atomic, independently shippable tasks
+
+## Branching Strategy
+
+```
+main
+└── feature/{feature-slug}
+    └── feature/{feature-slug}/{subfeature-slug}
+```
+
+- Feature branches from `main`
+- Subfeature branches from feature branch
+- TODOs committed directly to their subfeature/feature branch
+- Merge via PR with passing quality checks
+
+## PR Scope
+
+- One feature per PR (all its TODOs ship together)
+- If feature has subfeatures: one subfeature per PR
+- Subfeature PRs merge into feature branch, then feature branch merges into main
+- Atomic commits within PR (each TODO = 1-2 commits)
+
+## OODA Execution Loop
+
+```
+OBSERVE → ORIENT → DECIDE → ACT → loop
+```
+
+| Phase | Action | Cost |
+|-------|--------|------|
+| OBSERVE | git status, deps, retry patterns | Free (bash) |
+| ORIENT | Confidence calculation, pattern match | Free (rules) |
+| DECIDE | Route: execute/skip/replan/escalate | Free (lookup) |
+| ACT | TDD cycle (red → green → refactor → verify) | Normal |
+
+### Confidence Levels
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| High (0.7+) | No warnings, similar TODOs passed | Execute |
+| Medium (0.4-0.7) | Some warnings, retries in module | Execute cautiously |
+| Low (<0.4) | Patterns detected, failures clustered | Replan or escalate |
+
+### Guardrails
+
+| Limit | Default | Purpose |
+|-------|---------|---------|
+| `max_retries_per_todo` | 3 | Stop same approach |
+| `max_replans_per_module` | 2 | Stop different approaches |
+| `on_limit_hit` | escalate | Human decides |
+
+## Quality Gate Checklist
+
+Before marking a TODO complete:
+
+- [ ] Tests written and passing
+- [ ] Lint passing
+- [ ] Type check passing (if applicable)
+- [ ] No new warnings introduced
+- [ ] Changes are minimal and focused
+- [ ] Commit message follows convention
+
+## Stop Conditions
+
+Stop and ask human when:
+
+- Scope creep detected (TODO touches unexpected areas)
+- Guardrail limit hit (max retries or replans)
+- Security concern identified
+- Architectural decision needed
+- Dependencies need approval
+- Confidence stays low after replan
+
+## Parallel Work Rules
+
+TODOs can run in parallel when:
+
+- They have no file overlap
+- They have no data dependencies
+- Different owners (dev vs tester)
+
+Mark `depends_on` in TODO spec when sequential execution required.
+
+## Context Management
+
+- Use Explore subagent for codebase research
+- Suggest `/compact` after completing TODO
+- Keep main context focused on current task
+- Summarize findings, don't dump raw data