forge-dev-framework 1.1.0 → 1.2.0

package/dist/templates/.claude/rules/testing-standards.md.template

@@ -0,0 +1,280 @@
+# Testing Standards — {{projectName}}
+
+> **Scope:** All testing activities | **Loaded On-Demand**
+
+---
+
+## Testing Philosophy
+
+{{#if testingPhilosophy}}
+{{testingPhilosophy}}
+{{else}}
+- **Tests are documentation** — Readability matters
+- **Fast feedback** — Unit tests should run in < 1 second
+- **Test behavior, not implementation** — Black-box over white-box
+- **Arrange-Act-Assert** — Clear test structure
+- **One assertion per test** — When possible
+{{/if}}
+
+---
+
+## Test Structure
+
+### File Organization
+{{#if testStructure}}
+{{testStructure}}
+{{else}}
+```
+src/
+├── features/auth/
+│   ├── auth.service.ts
+│   ├── auth.service.test.ts      # Unit tests
+│   ├── auth.controller.ts
+│   └── auth.controller.test.ts   # Integration tests
+├── __tests__/
+│   ├── e2e/                      # End-to-end tests
+│   └── fixtures/                 # Test data, factories
+└── test/
+    ├── setup.ts                   # Global test setup
+    └── teardown.ts                # Global test teardown
+```
+{{/if}}
+
+### Test File Naming
+{{#if testNaming}}
+{{testNaming}}
+{{else}}
+- Unit tests: `*.test.ts` or `*.spec.ts`
+- E2E tests: `*.e2e.test.ts`
+- Co-locate tests with source code
+{{/if}}
+
+---
+
+## Unit Tests
+
+### What to Test
+{{#if unitTestScope}}
+{{unitTestScope}}
+{{else}}
+- **Business logic** — Pure functions, services
+- **Utilities** — Helpers, formatters
+- **Components** — React/Vue/Svelte components
+- **Hooks** — Custom React hooks
+
+### What NOT to Test
+- Third-party libraries (trust them)
+- Implementation details (private methods)
+- Trivial getters/setters
+{{/if}}
+
+### Test Template
+```typescript
+describe('{{feature}}', () => {
+  describe('{{scenario}}', () => {
+    it('{{expected outcome}}', () => {
+      // Arrange
+      const input = {
+        // setup
+      };
+
+      // Act
+      const result = doSomething(input);
+
+      // Assert
+      expect(result).toBe(expected);
+    });
+  });
+});
+```
+
+### Coverage Requirements
+{{#if coverage}}
+{{coverage}}
+{{else}}
+- Minimum: {{coverage.min}}% overall
+- Critical paths: 100%
+- New code: 100% before merge
+{{/if}}
+
+---
+
+## Integration Tests
+
+### Scope
+{{#if integrationScope}}
+{{integrationScope}}
+{{else}}
+- API endpoints with real database (in-memory)
+- Database interactions and migrations
+- Authentication/authorization flows
+- External service integrations (mocked)
+{{/if}}
+
+### Database Testing
+{{#if dbTesting}}
+{{dbTesting}}
+{{else}}
+- Use in-memory database for tests
+- Migrate up/down in `beforeAll`/`afterAll`
+- Seed test data in `beforeEach`
+- Clean tables in `afterEach`
+{{/if}}
+
+---
+
+## End-to-End Tests
+
+### Framework
+{{#if e2eFramework}}
+{{e2eFramework}}
+{{else}}
+- Use {{e2eTool}} (Playwright/Cypress)
+- Test critical user journeys
+- Run in CI before deployment
+{{/if}}
+
+### E2E Test Checklist
+{{#if e2eChecklist}}
+{{e2eChecklist}}
+{{else}}
+{{#each e2eScenarios}}
+- {{this}}
+{{/each}}
+{{/if}}
+
+---
+
+## Test Data Management
+
+### Factories & Fixtures
+{{#if testFactories}}
+{{testFactories}}
+{{else}}
+Use factories for test data:
+
+```typescript
+// test/factories/user.factory.ts
+export const userFactory = (overrides = {}) => ({
+  id: 'user-1',
+  email: 'test@example.com',
+  name: 'Test User',
+  role: 'user',
+  ...overrides,
+});
+```
+{{/if}}
+
+### Seeding Strategy
+{{#if seedingStrategy}}
+{{seedingStrategy}}
+{{else}}
+- Use deterministic IDs
+- Clean database between tests
+- Use transactions when possible
+{{/if}}
+
+---
+
+## Mocking & Stubbing
+
+### Mocking Guidelines
+{{#if mockingGuidelines}}
+{{mockingGuidelines}}
+{{else}}
+- Mock external services only
+- Prefer real implementations over mocks
+- Clear mocks in `afterEach`
+- Verify mock calls when relevant
+{{/if}}
+
+### Example
+```typescript
+jest.mock('./external-api', () => ({
+  getData: jest.fn().mockResolvedValue({ data: 'mock' }),
+}));
+
+// In test
+await expect(action()).resolves.toEqual(expected);
+expect(externalApi.getData).toHaveBeenCalledWith(expectedArgs);
+```
+
+---
+
+## Performance Tests
+
+{{#if performanceTests}}
+{{performanceTests}}
+{{else}}
+- Load test API endpoints (k6, artillery)
+- Benchmark critical functions
+- Test database query performance
+- Set performance budgets in CI
+{{/if}}
+
+---
+
+## Security Tests
+
+{{#if securityTests}}
+{{securityTests}}
+{{else}}
+- Test authentication bypass attempts
+- Test authorization checks
+- Test input validation (SQL injection, XSS)
+- Test rate limiting
+- Run SAST/DAST scans in CI
+{{/if}}
+
+---
+
+## Test Commands
+
+{{#if testCommands}}
+{{testCommands}}
+{{else}}
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm test -- --coverage
+
+# Run watch mode
+npm test -- --watch
+
+# Run specific test file
+npm test -- auth.service.test
+
+# Run E2E tests
+npm run test:e2e
+
+# Run performance tests
+npm run test:performance
+```
+{{/if}}
+
+---
+
+## CI/CD Integration
+
+{{#if ciTesting}}
+{{ciTesting}}
+{{else}}
+### Required Checks
+- Unit tests pass
+- Coverage threshold met
+- E2E tests pass (on main branch)
+- Security scan passes
+- Linting passes
+
+### Test Results
+- Upload coverage reports
+- Visualize test trends
+- Report flaky tests
+{{/if}}
+
+---
+
+> **Token Budget:** ~1000 tokens max
+> **Loaded On-Demand** — Only when working on tests

package/dist/templates/.claude/rules/ui-conventions.md.template

@@ -0,0 +1,264 @@
+# UI Conventions — {{projectName}}
+
+> **Scope:** Frontend UI development | **Loaded On-Demand**
+
+---
+
+## Design Principles
+
+{{#if designPrinciples}}
+{{#each designPrinciples}}
+- {{this}}
+{{/each}}
+{{else}}
+- **Clarity over cleverness** — UI should be self-explanatory
+- **Progressive disclosure** — Show complexity only when needed
+- **Responsive by default** — Mobile-first approach
+- **Accessibility first** — WCAG 2.1 AA compliance minimum
+{{/if}}
+
+---
+
+## Component Structure
+
+### File Organization
+{{#if componentStructure}}
+{{componentStructure}}
+{{else}}
+```
+src/
+├── components/
+│   ├── ui/              # Reusable UI primitives
+│   ├── features/        # Feature-specific components
+│   └── layouts/         # Layout components
+├── hooks/               # Custom React hooks
+├── lib/                 # Utility functions
+└── styles/              # Global styles
+```
+{{/if}}
+
+### Component Naming
+{{#if componentNaming}}
+{{componentNaming}}
+{{else}}
+- Use PascalCase: `UserProfile.tsx`, `DataTable.tsx`
+- One component per file
+- Co-locate related files:
+  - `UserProfile.tsx`
+  - `UserProfile.test.tsx`
+  - `UserProfile.stories.tsx`
+  - `user-profile.module.css`
+{{/if}}
+
+---
+
+## Styling Conventions
+
+{{#if styling}}
+{{styling}}
+{{else}}
+### CSS Approach
+- Use CSS Modules or Tailwind (configured in project)
+- No inline styles (except dynamic values)
+- Scoped styles only
+
+### Tailwind Conventions (if applicable)
+- Use utility classes for layout, spacing, colors
+- Create `@apply` components for repeated patterns
+- Don't override component props with arbitrary values
+
+### Theme Variables
+```css
+:root {
+  --color-primary: ...;
+  --color-success: ...;
+  --color-error: ...;
+  --spacing-unit: ...;
+  --radius-sm: ...;
+  --radius-md: ...;
+}
+```
+{{/if}}
+
+---
+
+## Form Patterns
+
+{{#if formPatterns}}
+{{formPatterns}}
+{{else}}
+### Form Validation
+- Client-side validation before submission
+- Show inline errors immediately
+- Disable submit button during submission
+- Clear errors on input change
+
+### Error Display
+- Red outline + error text below field
+- Group errors at top for complex forms
+- Highlight first error field on load
+
+### Success Feedback
+- Toast notification on success
+- Redirect or clear form as appropriate
+{{/if}}
+
+---
+
+## Loading States
+
+{{#if loadingStates}}
+{{loadingStates}}
+{{else}}
+### Skeleton Loading
+- Use skeleton screens for lists, tables
+- Maintain same layout as loaded state
+- Smooth fade-in when content loads
+
+### Button States
+- Show spinner + "Loading..." text
+- Disable button during action
+- Maintain button width to prevent layout shift
+{{/if}}
+
+---
+
+## Empty States
+
+{{#if emptyStates}}
+{{emptyStates}}
+{{else}}
+Every list/table must handle:
+1. **Loading** — Skeleton or spinner
+2. **Empty** — Friendly message + action button
+3. **Error** — Error message + retry button
+4. **No Results** — Message when filters return zero results
+
+Example:
+```
+┌─────────────────────────────┐
+│     No users found           │
+│                             │
+│  Try adjusting your filters  │
+│  or create a new user        │
+│                             │
+│    [Create New User]         │
+└─────────────────────────────┘
+```
+{{/if}}
+
+---
+
+## Responsive Breakpoints
+
+{{#if breakpoints}}
+{{breakpoints}}
+{{else}}
+- Mobile: < 640px
+- Tablet: 640px — 1024px
+- Desktop: > 1024px
+- Large Desktop: > 1280px
+
+Test on real devices or browser dev tools.
+{{/if}}
+
+---
+
+## Accessibility
+
+{{#if accessibility}}
+{{accessibility}}
+{{else}}
+### Minimum Requirements
+- Keyboard navigation for all interactive elements
+- ARIA labels for icon-only buttons
+- Focus indicators on all focusable elements
+- Screen reader text for status messages
+- Color contrast minimum 4.5:1
+
+### Testing
+- Test with keyboard only
+- Test with screen reader (NVDA/VoiceOver)
+- Use axe DevTools extension
+{{/if}}
+
+---
+
+## Data Display
+
+### Tables
+{{#if tablePatterns}}
+{{tablePatterns}}
+{{else}}
+- Sortable headers
+- Pagination (20 rows default)
+- Column filtering for complex tables
+- Row actions menu (⋮)
+- Responsive: card view on mobile
+
+### Status Indicators
+Use consistent colors:
+- 🟢 Green — Active, Success, Online
+- 🟡 Yellow — Pending, Warning, Away
+- 🔴 Red — Error, Failed, Offline
+- 🔵 Blue — Info, Neutral
+- ⚪ Gray — Disabled, Inactive
+{{/if}}
+
+---
+
+## Performance
+
+{{#if performance}}
+{{performance}}
+{{else}}
+### Code Splitting
+- Route-based splitting (automatic)
+- Lazy load heavy components
+- Preload critical resources
+
+### Rendering
+- Use `React.memo` for expensive components
+- Debounce search inputs (300ms)
+- Virtualize long lists (> 100 items)
+{{/if}}
+
+---
+
+## Icon Usage
+
+{{#if icons}}
+{{icons}}
+{{else}}
+- Use {{iconSet}} for icons
+- Standard icon sizes: sm (16px), md (20px), lg (24px), xl (32px)
+- Match icon size to adjacent text
+- Add aria-label for icon-only buttons
+{{/if}}
+
+---
+
+## Typography
+
+{{#if typography}}
+{{typography}}
+{{else}}
+### Font Hierarchy
+- Heading 1: 32px (page titles)
+- Heading 2: 24px (section titles)
+- Heading 3: 18px (card titles)
+- Body: 16px (default)
+- Small: 14px (labels, metadata)
+- XSmall: 12px (captions, timestamps)
+
+### Font Weights
+- Regular (400) — body text
+- Medium (500) — labels, buttons
+- Semibold (600) — headings, emphasized text
+- Bold (700) — rarely used
+{{/if}}
+
+---
+
+> **Token Budget:** ~1000 tokens max
+> **Loaded On-Demand** — Only when working on UI code

package/dist/templates/.planning/forge.config.json.template

@@ -0,0 +1,75 @@
+{
+  "$schema": "../src/schemas/forge.config.schema.json",
+  "project": {
+    "name": "{{projectName}}",
+    "version": "{{version}}",
+    "status": "initialized"
+  },
+  "mode": "{{mode}}",
+  "depth": "{{depth}}",
+  "maxTeammates": {{maxTeammates}},
+  "taskLimit": {{taskLimit}},
+
+  "agentProfile": "{{agentProfile}}",
+  "workflow": {
+    "research": {{workflow.research}},
+    "planCheck": {{workflow.planCheck}},
+    "tribunal": {{workflow.tribunal}},
+    "contractFirst": {{workflow.contractFirst}}
+  },
+
+  "git": {
+    "strategy": "{{git.strategy}}",
+    "branchTemplate": "{{git.branchTemplate}}",
+    "squashOnShip": {{git.squashOnShip}}
+  },
+
+  "paths": {
+    "artifacts": "./",
+    "state": "./state",
+    "events": "./state/events",
+    "contracts": "./contracts",
+    "planning": "./.planning",
+    "worktrees": "./.worktrees"
+  },
+
+  "templates": {
+    "claude": "./src/templates/CLAUDE.md.template",
+    "project": "./src/templates/PROJECT.md.template",
+    "requirements": "./src/templates/REQUIREMENTS.md.template",
+    "roadmap": "./src/templates/ROADMAP.md.template",
+    "plan": "./src/templates/PLAN.md.template",
+    "rules": "./src/templates/.claude/rules",
+    "config": "./src/templates/.planning/forge.config.json.template"
+  },
+
+  "tokenLimits": {
+    "claude": 2000,
+    "requirements": 4000,
+    "plan": 6000,
+    "rules": 1000
+  },
+
+  "roles": {
+    "team-lead": {
+      "name": "Team Lead",
+      "description": "Coordinates the team, manages state, approves artifacts"
+    },
+    "backend": {
+      "name": "Backend Specialist",
+      "description": "Owns /src/api, /src/db, API contracts"
+    },
+    "frontend": {
+      "name": "Frontend Specialist",
+      "description": "Owns /src/ui, /src/components, frontend contracts"
+    },
+    "qa": {
+      "name": "QA Specialist",
+      "description": "Owns /tests, /e2e, quality assurance"
+    },
+    "templates": {
+      "name": "Templates Specialist",
+      "description": "Owns /src/templates, /src/generators, artifact generation"
+    }
+  }
+}