codecruise 0.1.0

package/config/skills/typescript/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: typescript
+description: TypeScript strict patterns and type safety
+version: 1.0.0
+triggers:
+  - "*.ts"
+  - "*.tsx"
+  - types
+  - strict
+  - zod
+---
+
+# TypeScript Skill
+
+Strict TypeScript patterns for type-safe, maintainable code.
+
+## Quick Reference
+
+| ID | Rule | Priority |
+|----|------|----------|
+| ts-1 | Enable strict mode in tsconfig.json | CRITICAL |
+| ts-2 | Never use `any`, use `unknown` for unknown types | CRITICAL |
+| ts-3 | Use Zod for runtime validation at boundaries | CRITICAL |
+| ts-4 | Prefer `interface` for objects, `type` for unions | HIGH |
+| ts-5 | Use `as const` for literal types | HIGH |
+| ts-6 | Avoid type assertions, use type guards | HIGH |
+| ts-7 | Use discriminated unions for state machines | HIGH |
+| ts-8 | Return `Result<T, E>` for operations that can fail | HIGH |
+| ts-9 | Use branded types for IDs and special strings | MEDIUM |
+| ts-10 | Prefer `readonly` for immutable data | MEDIUM |
+| ts-11 | Use `satisfies` for type checking without widening | MEDIUM |
+| ts-12 | Colocate types with implementation | MEDIUM |
+| ts-13 | Export types separately from runtime code | LOW |
+| ts-14 | Use `NonNullable<T>` after null checks | LOW |
+| ts-15 | Avoid enums, use const objects with `as const` | LOW |
+
+## Critical Rules (Always Apply)
+
+### ts-1: Strict Mode
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "exactOptionalPropertyTypes": true
+  }
+}
+```
+
+### ts-2: No Any
+
+```typescript
+// BAD
+function process(data: any) { return data.value }
+
+// GOOD
+function process(data: unknown) {
+  if (isValid(data)) return data.value
+}
+```
+
+### ts-3: Zod at Boundaries
+
+```typescript
+const UserSchema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+});
+type User = z.infer<typeof UserSchema>;
+
+// Validate external input
+const user = UserSchema.parse(request.body);
+```
+
+### ts-7: Discriminated Unions
+
+```typescript
+type AsyncState<T> =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: T }
+  | { status: 'error'; error: Error };
+```
+
+### ts-8: Result Type
+
+```typescript
+type Result<T, E = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+function parse(json: string): Result<object> {
+  try {
+    return { ok: true, value: JSON.parse(json) };
+  } catch (e) {
+    return { ok: false, error: e as Error };
+  }
+}
+```
+
+### ts-9: Branded Types
+
+```typescript
+type UserId = string & { readonly __brand: 'UserId' };
+type PostId = string & { readonly __brand: 'PostId' };
+
+// Prevents mixing up IDs
+function getUser(id: UserId) { }
+function getPost(id: PostId) { }
+```
+
+### ts-6: Type Guards
+
+```typescript
+function isUser(value: unknown): value is User {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'id' in value &&
+    'email' in value
+  );
+}
+```
+
+### ts-5: Const Assertions
+
+```typescript
+const ROLES = ['admin', 'user', 'guest'] as const;
+type Role = typeof ROLES[number]; // 'admin' | 'user' | 'guest'
+
+const CONFIG = {
+  apiUrl: 'https://api.example.com',
+  timeout: 5000,
+} as const;
+```
+
+### ts-15: Avoid Enums
+
+```typescript
+// BAD
+enum Status { Active, Inactive }
+
+// GOOD
+const Status = {
+  Active: 'active',
+  Inactive: 'inactive',
+} as const;
+type Status = typeof Status[keyof typeof Status];
+```

package/config/templates/CLAUDE.md

@@ -0,0 +1,70 @@
+# {Project Name}
+
+<!-- Keep this file <100 lines. Use steering docs for details. -->
+
+## What
+
+{One-liner: "{Project} is a {type} that {value} for {audience}."}
+
+## Stack
+
+- **Language**: {e.g., TypeScript 5.x}
+- **Runtime**: {e.g., Node 20, Bun 1.x}
+- **Framework**: {e.g., Next.js 14, Express}
+- **Package Manager**: {npm|pnpm|yarn|bun}
+
+## Quality Command
+
+```bash
+{single command that runs lint + typecheck + tests, must be <10s}
+```
+
+## Key Commands
+
+```bash
+{install_command}        # Install dependencies
+{dev_command}            # Start dev server
+{build_command}          # Production build
+{test_command}           # Run tests
+```
+
+## Project Structure
+
+```
+src/
+├── {main_dir}/          # {purpose}
+├── {main_dir}/          # {purpose}
+└── {main_dir}/          # {purpose}
+```
+
+## Steering Docs
+
+<!-- Progressive disclosure: details live in these files -->
+
+| Doc | Purpose |
+|-----|---------|
+| `.codecruise/steering/product.md` | What we're building, users, scope |
+| `.codecruise/steering/tech.md` | Full stack details, constraints |
+| `.codecruise/steering/structure.md` | Architecture, patterns, conventions |
+| `.codecruise/canon/spec.md` | Detailed requirements (FR/NFR) |
+| `.codecruise/canon/decisions.md` | Architecture decisions (ADRs) |
+
+## Rules
+
+<!-- Only universally applicable rules. Max 10. -->
+
+1. TDD: Write tests before implementation
+2. No secrets in code/logs/commits
+3. No new dependencies without approval
+4. Atomic commits: one logical change per commit
+5. Update `progress.yaml` after every task
+
+## Domain Context
+
+<!-- 1-2 sentences of domain expertise that helps understanding -->
+
+{e.g., "Fintech app handling multi-currency. Decimal precision critical. PCI compliance required."}
+
+---
+
+*Generated by codecruise. Edit steering docs for details.*

package/config/templates/README.md

@@ -0,0 +1,117 @@
+# CodeCruise Templates
+
+World-class documentation templates based on industry best practices.
+
+## Sources & Inspiration
+
+| Template | Based On |
+|----------|----------|
+| CLAUDE.md | [HumanLayer best practices](https://www.humanlayer.dev/blog/writing-a-good-claude-md), [AGENTS.md spec](https://agents.md/) |
+| product.md | PRD templates from Google, Amazon, HashiCorp |
+| tech.md | Tech stack documentation patterns |
+| structure.md | [C4 Model](https://c4model.com/), folder conventions |
+| adr-template.md | [ADR GitHub](https://github.com/joelparkerhenderson/architecture-decision-record), MADR format |
+| rfc-template.md | [Pragmatic Engineer](https://newsletter.pragmaticengineer.com/p/rfcs-and-design-docs), Rust RFC process |
+
+## Design Principles
+
+### 1. Progressive Disclosure
+
+CLAUDE.md is minimal (<100 lines). Details live in steering docs.
+
+```
+CLAUDE.md (always loaded, ~100 lines)          # Claude Code requirement
+    │
+    ├── .codecruise/steering/product.md        # CodeCruise steering
+    ├── .codecruise/steering/tech.md           # CodeCruise steering
+    ├── .codecruise/steering/structure.md      # CodeCruise steering
+    └── .codecruise/canon/spec.md              # Canonical spec
+```
+
+### 2. Separation of Concerns
+
+| Doc | Answers |
+|-----|---------|
+| product.md | **What** are we building and **why**? |
+| tech.md | **How** are we building it (tools)? |
+| structure.md | **Where** does code go (architecture)? |
+| spec.md | **What exactly** (detailed requirements)? |
+| decisions.md | **Why** did we choose X over Y? |
+
+### 3. AI-First Design
+
+- Clear, structured sections (easy to parse)
+- Explicit over implicit
+- Tables over prose (faster scanning)
+- Commands over descriptions (actionable)
+
+### 4. Living Documentation
+
+- Templates include `Last updated: {date}`
+- `/doctor --validate-steering` checks for staleness
+- ADRs are append-only (immutable decisions)
+
+## Template Structure
+
+```
+config/templates/
+├── CLAUDE.md                    # Minimal project context
+├── README.md                    # This file
+└── steering/
+    ├── product.md               # Product context
+    ├── tech.md                  # Tech stack
+    ├── structure.md             # Architecture & conventions
+    ├── adr-template.md          # Architecture Decision Record
+    └── rfc-template.md          # Request for Comments
+```
+
+## Usage
+
+### Via /init
+
+```bash
+/init                    # Creates CLAUDE.md + steering docs
+/init --minimal          # CLAUDE.md only
+/init --full             # All templates including RFC/ADR
+```
+
+### Manual
+
+Copy templates to your project:
+
+```bash
+# CLAUDE.md goes in project root (Claude Code requirement)
+cp ~/.claude/templates/CLAUDE.md ./CLAUDE.md
+
+# Steering docs go in .codecruise/
+mkdir -p .codecruise/steering
+cp ~/.claude/templates/steering/*.md .codecruise/steering/
+```
+
+## Validation
+
+```bash
+/doctor --validate-steering    # Check steering docs exist and are current
+```
+
+| Check | Pass | Warn | Fail |
+|-------|------|------|------|
+| CLAUDE.md exists | Present | — | Missing |
+| CLAUDE.md < 150 lines | Yes | 150-300 lines | > 300 lines |
+| product.md exists | Present | — | Missing |
+| tech.md exists | Present | — | Missing |
+| structure.md exists | Present | — | Missing |
+| Docs updated < 30 days | Yes | 30-90 days | > 90 days |
+| Quality command works | Passes | — | Fails |
+
+## Comparison with Alternatives
+
+| Feature | CodeCruise | Kiro | AGENTS.md |
+|---------|------------|------|-----------|
+| Minimal CLAUDE.md | ✅ <100 lines | ⚠️ No guidance | ✅ |
+| Progressive disclosure | ✅ Steering docs | ✅ Steering dir | ❌ |
+| Structured templates | ✅ | ⚠️ Basic | ❌ |
+| Validation | ✅ /doctor | ❌ | ❌ |
+| ADR support | ✅ Template | ❌ | ❌ |
+| RFC support | ✅ Template | ❌ | ❌ |
+| Schema enforcement | ✅ schemas.md | ❌ | ❌ |

package/config/templates/steering/adr-template.md

@@ -0,0 +1,102 @@
+# ADR-{NNN}: {Title}
+
+> Architecture Decision Record
+
+## Status
+
+<!-- Proposed | Accepted | Deprecated | Superseded by ADR-XXX -->
+**Proposed** — {date}
+
+## Context
+
+<!--
+What is the issue? What forces are at play?
+Include: technical constraints, business requirements, team factors
+-->
+
+## Decision Drivers
+
+<!-- Key factors influencing this decision -->
+
+- {driver 1}
+- {driver 2}
+- {driver 3}
+
+## Considered Options
+
+### Option 1: {Name}
+
+**Description**: {brief description}
+
+| Pros | Cons |
+|------|------|
+| | |
+
+### Option 2: {Name}
+
+**Description**: {brief description}
+
+| Pros | Cons |
+|------|------|
+| | |
+
+### Option 3: {Name}
+
+**Description**: {brief description}
+
+| Pros | Cons |
+|------|------|
+| | |
+
+## Decision
+
+<!-- What is the change that we're proposing and/or doing? -->
+
+We will use **{Option X}** because {primary rationale}.
+
+## Consequences
+
+### Positive
+
+- {consequence}
+- {consequence}
+
+### Negative
+
+- {consequence}
+- {consequence}
+
+### Neutral
+
+- {consequence}
+
+## Implementation
+
+<!-- How will this be implemented? Key steps. -->
+
+1. {step}
+2. {step}
+3. {step}
+
+## Validation
+
+<!-- How do we know this decision is working? -->
+
+- [ ] {validation criterion}
+- [ ] {validation criterion}
+
+## Related
+
+<!-- Links to related ADRs, specs, or documents -->
+
+- Related ADRs: {ADR-XXX}
+- Related Requirements: {FR-XXX, NFR-XXX}
+- Related Issues: {conflict-XXX, oq-XXX}
+
+---
+
+## Changelog
+
+| Date | Author | Change |
+|------|--------|--------|
+| {date} | {name} | Initial proposal |

package/config/templates/steering/product.md

@@ -0,0 +1,60 @@
+# Product Context
+
+> What we're building and why it matters.
+
+## One-Liner
+
+<!-- Complete this sentence: "{Project} is a {type} that {value prop} for {audience}." -->
+{Project} is a _____ that _____ for _____.
+
+## Problem Statement
+
+<!-- What pain point does this solve? Be specific. -->
+
+## Target Users
+
+<!-- Who uses this? List 2-3 personas with their goals. -->
+
+| Persona | Role | Primary Goal | Pain Point |
+|---------|------|--------------|------------|
+| | | | |
+
+## Value Proposition
+
+<!-- Why would someone choose this over alternatives? -->
+
+## Key Features (v1 Scope)
+
+<!-- Prioritized list. Be ruthless about scope. -->
+
+1. **{Feature}** — {one-line description}
+2. **{Feature}** — {one-line description}
+3. **{Feature}** — {one-line description}
+
+## Out of Scope (v1)
+
+<!-- Explicitly list what you're NOT building. Prevents scope creep. -->
+
+-
+-
+
+## Success Metrics
+
+<!-- How do you know if this is working? -->
+
+| Metric | Target | Measurement |
+|--------|--------|-------------|
+| | | |
+
+## Competitive Context
+
+<!-- What alternatives exist? How is this different? -->
+
+| Alternative | Strength | Our Differentiation |
+|-------------|----------|---------------------|
+| | | |
+
+---
+
+*Last updated: {date}*
+*Owner: {name}*

package/config/templates/steering/rfc-template.md

@@ -0,0 +1,159 @@
+# RFC-{NNN}: {Title}
+
+> Request for Comments — {feature/change description}
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| Author | {name} |
+| Status | Draft / In Review / Accepted / Rejected / Implemented |
+| Created | {date} |
+| Updated | {date} |
+| Reviewers | {names} |
+| Target Release | {version/date} |
+
+## Summary
+
+<!-- One paragraph. What are you proposing? -->
+
+## Motivation
+
+<!-- Why are we doing this? What problem does it solve? -->
+
+### Problem Statement
+
+### User Impact
+
+### Business Value
+
+## Detailed Design
+
+### Overview
+
+<!-- High-level approach -->
+
+### Architecture
+
+<!-- Include diagrams where helpful -->
+
+```mermaid
+flowchart TD
+    A[Component] --> B[Component]
+    B --> C[Component]
+```
+
+### API Changes
+
+<!-- If applicable -->
+
+```typescript
+// Before
+interface OldAPI {}
+
+// After
+interface NewAPI {}
+```
+
+### Data Model Changes
+
+<!-- If applicable -->
+
+### Migration Path
+
+<!-- How do we get from current state to proposed state? -->
+
+1. {step}
+2. {step}
+3. {step}
+
+## Alternatives Considered
+
+### Alternative 1: {Name}
+
+**Why not**: {reason}
+
+### Alternative 2: {Name}
+
+**Why not**: {reason}
+
+## Risks and Mitigations
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| | | | |
+
+## Security Considerations
+
+<!-- Any security implications? -->
+
+## Performance Considerations
+
+<!-- Any performance implications? -->
+
+## Testing Strategy
+
+<!-- How will this be tested? -->
+
+- Unit tests:
+- Integration tests:
+- E2E tests:
+- Performance tests:
+
+## Rollout Plan
+
+<!-- How will this be deployed? -->
+
+| Phase | Scope | Success Criteria | Rollback Plan |
+|-------|-------|------------------|---------------|
+| | | | |
+
+## Success Metrics
+
+<!-- How do we measure success? -->
+
+| Metric | Current | Target | Measurement |
+|--------|---------|--------|-------------|
+| | | | |
+
+## Open Questions
+
+<!-- Questions that need resolution -->
+
+- [ ] {question}
+- [ ] {question}
+
+## Dependencies
+
+<!-- External dependencies or blockers -->
+
+- {dependency}
+
+## Timeline
+
+| Milestone | Target Date | Status |
+|-----------|-------------|--------|
+| RFC Approved | | |
+| Implementation Start | | |
+| Alpha/Beta | | |
+| GA Release | | |
+
+---
+
+## Discussion
+
+<!-- Feedback and discussion notes go here -->
+
+### {date} — {reviewer}
+
+{feedback}
+
+---
+
+## Resolution
+
+<!-- Final decision after RFC process -->
+
+**Decision**: {Accepted/Rejected/Modified}
+**Rationale**: {why}
+**Next Steps**: {what happens now}