@jadeit/forge-ai 0.0.0 → 1.2.1

package/skills/forge-state-manager/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: forge-state-manager
+description: Manage Forge state transitions, phase tracking, feature status, and git hooks
+license: MIT
+compatibility: opencode
+metadata:
+  audience: forge-users
+  workflow: phase-execution
+---
+
+# Forge State Manager
+
+Manage Forge state transitions, phase tracking, feature status, and git commit hooks.
+
+## State File Location
+
+`.forge/state.yaml`
+
+## State Structure
+
+```yaml
+project_phase: 1
+phase_history:
+  - phase: 1
+    status: complete
+    started: 2026-03-20T10:00:00Z
+    completed: 2026-03-22T14:00:00Z
+
+features:
+  auth-system:
+    phase: 3
+    mode: brownfield
+    started: 2026-03-22T14:00:00Z
+    current_sub_phase: 5_implement
+    rework_tracking:
+      implement_loops: 0
+      approach_loops: 0
+      history: []
+    commits: []
+```
+
+## Operations
+
+### 1. Read Current State
+
+Read `.forge/state.yaml` to understand:
+- Current project phase
+- Phase history and completion status
+- Active features and their sub-phase
+
+### 2. Update Phase Status
+
+When completing a phase:
+```yaml
+phase_history:
+  - phase: 1
+    status: complete
+    started: 2026-03-20T10:00:00Z
+    completed: 2026-03-22T14:00:00Z
+  - phase: 2
+    status: in-progress
+    started: 2026-03-22T14:00:00Z
+```
+
+### 3. Update Feature Status
+
+When working on a feature:
+```yaml
+features:
+  feature-slug:
+    phase: 3
+    mode: brownfield
+    started: 2026-03-22T14:00:00Z
+    current_sub_phase: 5_implement
+    task_document: docs/design/tasks/feature-slug.md
+```
+
+### 4. Update Task Status
+
+In task document frontmatter:
+```yaml
+status: in-progress:approach  # When in approach phase
+status: complete              # When done
+```
+
+## Phase Transition Process
+
+### Before Transition
+
+1. **Check artifact completeness** for current phase:
+   - Phase 1: project-scope.md, user-stories.md, implementation-plan.md, technology-and-architecture.md
+   - Phase 2: design-decisions.md, task-list.md, all task documents with required frontmatter
+   - Phase 3: Task implementation complete, review passes, validation passes
+   - Phase 4: UAT results documented, user sign-off obtained
+   - Phase 5: Deployment verified
+   - Phase 6: Monitoring active
+
+2. **Propose transition** to user:
+   ```
+   Phase 1 complete — all required artifacts found:
+   - ✓ docs/planning/project-scope.md
+   - ✓ docs/planning/user-stories.md
+   - ✓ docs/planning/implementation-plan.md
+   - ✓ docs/planning/technology-and-architecture.md
+   
+   Confirm transition to Phase 2: Design?
+   ```
+
+3. **Wait for confirmation** before updating state
+
+### After Confirmation
+
+Update `.forge/state.yaml` with new phase and history entry
+
+## Prerequisite Checking
+
+### Check Function
+
+```
+function check_prerequisites(current_phase: int, target_phase: int) -> tuple[bool, list[str]]:
+    missing = []
+    if target_phase > 1 and current_phase < 1:
+        missing.append("Phase 1 (Planning) must be complete")
+    if target_phase > 2 and current_phase < 2:
+        missing.append("Phase 2 (Design) must be complete")
+    # ... etc
+    return (len(missing) == 0, missing)
+```
+
+### Gate Behaviour
+
+From `.forge/config.yaml`:
+```yaml
+gates:
+  warn_on_prerequisite_failure: true
+  allow_override: true
+```
+
+If prerequisites not met:
+1. **Warn** the user about missing prerequisites
+2. **List** what's missing
+3. **Allow override** if user confirms to proceed anyway
+
+## Feature Dev Sub-Phase Tracking
+
+Track progress through Feature Dev sub-phases in state:
+```yaml
+features:
+  feature-slug:
+    current_sub_phase: 5_implement
+    sub_phase_history:
+      - sub_phase: 1_discover
+        status: complete
+        completed: 2026-03-22T14:30:00Z
+      - sub_phase: 2_explore
+        status: complete
+        completed: 2026-03-22T15:00:00Z
+      - sub_phase: 3_clarify
+        status: complete
+        completed: 2026-03-22T15:30:00Z
+      - sub_phase: 4_approach
+        status: complete
+        completed: 2026-03-22T16:00:00Z
+```
+
+## Rework Loop Detection
+
+Track iterations when rework occurs.
+
+### Tracking
+
+Increment counters when rework happens:
+
+| Action | Counter to Increment |
+|--------|---------------------|
+| Review → Implement (minor fixes) | `implement_loops` |
+| Review → Approach (fundamental issues) | `approach_loops` |
+
+### State Update
+
+```yaml
+features:
+  feature-slug:
+    rework_tracking:
+      implement_loops: 1
+      approach_loops: 0
+      history:
+        - action: rework_implement
+          timestamp: 2026-03-22T16:00:00Z
+          reason: "Type check failures"
+```
+
+### Thresholds
+
+Default thresholds (from `.forge/config.yaml`):
+```yaml
+rework:
+  max_implement_loops: 3
+  max_approach_loops: 2
+```
+
+### Warning Format
+
+When threshold exceeded:
+```
+⚠️  Rework Alert: auth-system
+- Implement loops: 3/3 (MAX)
+- Approach loops: 1/2
+
+Consider:
+1. Pausing implementation
+2. Re-evaluating approach
+3. Requesting human review
+```
+
+### Reset on Success
+
+Reset counters when sub-phase completes successfully:
+```yaml
+rework_tracking:
+  implement_loops: 0
+  approach_loops: 0
+```
+
+## Rework State Management
+
+### Minor Issues (Loop to Implement)
+- Stay in current feature
+- Track iteration count in `rework_tracking.implement_loops`
+- Don't create new sub-phase entries
+
+### Approach Issues (Loop to Approach)
+- Move current_sub_phase back to "4_approach"
+- Track in `rework_tracking.approach_loops`
+- Note what changed in approach

package/skills/forge-template-loader/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: forge-template-loader
+description: Load and apply Forge document templates for all phases and artifacts
+license: MIT
+compatibility: opencode
+metadata:
+  audience: forge-users
+  workflow: document-creation
+---
+
+# Forge Template Loader
+
+Load and apply Forge document templates for all phases and artifacts.
+
+## Template Locations
+
+```
+.forge/templates/
+├── planning/
+│   ├── project-scope.md
+│   ├── user-stories.md
+│   ├── implementation-plan.md
+│   └── technology-and-architecture.md
+├── design/
+│   ├── design-decisions.md
+│   ├── task-list.md
+│   └── tasks/
+│       └── TASK_TEMPLATE.md
+├── testing/
+│   └── uat-results.md
+└── defects/
+    └── DEFECT_TEMPLATE.md
+```
+
+## Usage by Phase
+
+### Phase 1: Planning Templates
+
+Load from `.forge/templates/planning/`:
+
+| Document | Template | Output Location |
+|----------|----------|-----------------|
+| Project Scope | `project-scope.md` | `docs/planning/project-scope.md` |
+| User Stories | `user-stories.md` | `docs/planning/user-stories.md` |
+| Implementation Plan | `implementation-plan.md` | `docs/planning/implementation-plan.md` |
+| Technology & Architecture | `technology-and-architecture.md` | `docs/planning/technology-and-architecture.md` |
+
+### Phase 2: Design Templates
+
+Load from `.forge/templates/design/`:
+
+| Document | Template | Output Location |
+|----------|----------|-----------------|
+| Design Decisions | `design-decisions.md` | `docs/design/design-decisions.md` |
+| Task List | `task-list.md` | `docs/design/task-list.md` |
+| Individual Task | `tasks/TASK_TEMPLATE.md` | `docs/design/tasks/{task-slug}.md` |
+
+### Phase 4: Testing Templates
+
+| Document | Template | Output Location |
+|----------|----------|-----------------|
+| UAT Results | `testing/uat-results.md` | `docs/testing/uat-results.md` |
+
+### Defect Templates
+
+| Document | Template | Output Location |
+|----------|----------|-----------------|
+| Defect Report | `defects/DEFECT_TEMPLATE.md` | `docs/defects/{defect-slug}.md` |
+
+## Template Variables
+
+When applying templates, replace these placeholders:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `[Task Title]` | Title of the task | "Implement user authentication" |
+| `[Task Slug]` | URL-safe identifier | "implement-user-auth" |
+| `[YYYY-MM-DD]` | Date placeholder | "2026-03-22" |
+| `[timestamp]` | ISO 8601 timestamp | "2026-03-22T10:00:00Z" |
+| `[Persona]` | User persona name | "End User" |
+| `[Goal]` | User goal | "reset my password" |
+| `[Benefit]` | User benefit | " regain access to my account" |
+
+## Required Frontmatter Fields
+
+### Task Document
+
+```yaml
+---
+title: [Task Title]
+status: not-started
+mode: greenfield | brownfield
+complexity: small | medium | large
+categories:
+  - backend
+affected_modules: []
+dependencies: []
+---
+```
+
+### Defect Document
+
+```yaml
+---
+title: [Defect Title]
+severity: critical | high | medium | low
+classification: design | implementation
+status: open
+source:
+  type: sentry | logs | test | uat | user-report
+  url: null
+  discovered: [timestamp]
+affected_features: []
+routed_to: null
+---
+```
+
+## Template Application Process
+
+### Creating a New Document
+
+1. **Read the template** from `.forge/templates/`
+2. **Replace placeholders** with actual values
+3. **Set initial status** in frontmatter (e.g., `status: in-progress`)
+4. **Set dates** to current timestamp
+5. **Write to destination** in `docs/`
+
+### Example: Creating a Task Document
+
+```
+Input: TASK_TEMPLATE.md
+Variables:
+  title = "Implement user authentication"
+  slug = "implement-user-auth"
+  complexity = "medium"
+  categories = ["backend", "database"]
+
+Output: docs/design/tasks/implement-user-auth.md
+```
+
+## Template Validation
+
+After creating a document, validate:
+
+1. **Frontmatter present** - Document starts with `---`
+2. **Required fields** - All required fields populated
+3. **Valid enums** - Status, mode, complexity use valid values
+4. **File path** - Correct location and naming
+
+## Modifying Templates
+
+Templates can be customized per project:
+
+1. Copy from `.forge/templates/` to project root
+2. Modify as needed
+3. Use project-local template instead of global
+
+Or extend `.forge/config.yaml`:
+```yaml
+templates:
+  custom_path: .forge/templates-custom/
+```

package/templates/defects/DEFECT_TEMPLATE.md

@@ -0,0 +1,96 @@
+---
+title: [Defect Title]
+severity: critical
+classification: implementation
+status: open
+source:
+  type: sentry
+  url: null
+  discovered: null
+affected_features: []
+routed_to: null
+reproduction_steps: []
+expected_behaviour: null
+actual_behaviour: null
+created: null
+last_updated: null
+---
+
+# Defect Report: [Title]
+
+## Summary
+
+<!-- One-line summary of the defect -->
+
+## Severity
+
+- [ ] Critical - System unusable, data loss risk
+- [ ] High - Major feature broken, no workaround
+- [ ] Medium - Feature broken, workaround exists
+- [ ] Low - Minor issue, cosmetic
+
+## Classification
+
+- **Design** - Flawed design that needs revisiting
+- **Implementation** - Incorrect implementation of correct design
+
+## Source
+
+| Field | Value |
+|-------|-------|
+| Type | sentry / logs / test / uat / user-report |
+| URL | |
+| Discovered | |
+
+## Affected Features
+
+- 
+
+## Reproduction Steps
+
+1. 
+2. 
+3. 
+
+## Expected Behaviour
+
+<!-- What should happen -->
+
+## Actual Behaviour
+
+<!-- What actually happens -->
+
+## Screenshots / Logs
+
+<!-- Include relevant screenshots or log excerpts -->
+
+## Environment
+
+| Field | Value |
+|-------|-------|
+| Browser/OS | |
+| Version | |
+| User Type | |
+
+## Resolution
+
+### Routed To
+
+- Design phase (`forge 2:design`)
+- Build phase (`forge 3:build`)
+
+### Root Cause
+
+<!-- Analysis of the root cause -->
+
+### Fix Applied
+
+<!-- How the defect was resolved -->
+
+### Resolution Date
+
+## Changelog
+
+| Date | Action | By |
+|------|--------|-----|
+|      |        |     |

package/templates/design/design-decisions.md

@@ -0,0 +1,64 @@
+---
+title: Design Decisions
+phase: 2
+status: in-progress
+created: null
+last_updated: null
+---
+
+# Design Decisions
+
+## Decision Record Template
+
+| Field | Value |
+|-------|-------|
+| **Decision ID** | ADDR-001 |
+| **Date** | YYYY-MM-DD |
+| **Status** | Proposed / Accepted / Deprecated |
+| **Deciders** | |
+| **Context** | |
+| **Decision** | |
+| **Consequences** | |
+
+---
+
+## ADDR-001: [Title]
+
+**Status:** Accepted
+
+### Context
+
+<!-- What is the issue or decision being addressed? -->
+
+### Decision
+
+<!-- What is the change that is proposed or has been made? -->
+
+### Alternatives Considered
+
+1. **Option A:** 
+   - Pros: 
+   - Cons: 
+
+2. **Option B:** 
+   - Pros: 
+   - Cons: 
+
+### Consequences
+
+**Positive:**
+- 
+
+**Negative:**
+- 
+
+**Neutral:**
+- 
+
+---
+
+## Decision Index
+
+| ID | Title | Status | Date |
+|----|-------|--------|------|
+| ADDR-001 |        |        |      |

package/templates/design/task-list.md

@@ -0,0 +1,56 @@
+---
+title: Task List
+phase: 2
+status: in-progress
+created: null
+last_updated: null
+---
+
+# Task List
+
+## Summary
+
+| Total Tasks | Small | Medium | Large |
+|-------------|-------|--------|-------|
+|             |       |        |       |
+
+## Tasks by Category
+
+### Backend
+| Task Slug | Title | Complexity | Dependencies |
+|-----------|-------|------------|--------------|
+|           |       |            |              |
+
+### Frontend
+| Task Slug | Title | Complexity | Dependencies |
+|-----------|-------|------------|--------------|
+|           |       |            |              |
+
+### Infrastructure
+| Task Slug | Title | Complexity | Dependencies |
+|-----------|-------|------------|--------------|
+|           |       |            |              |
+
+### Database
+| Task Slug | Title | Complexity | Dependencies |
+|-----------|-------|------------|--------------|
+|           |       |            |              |
+
+### Documentation
+| Task Slug | Title | Complexity | Dependencies |
+|-----------|-------|------------|--------------|
+|           |       |            |              |
+
+## Task Dependencies Graph
+
+```mermaid
+flowchart LR
+    A[Task A] --> B[Task B]
+    B --> C[Task C]
+```
+
+## Implementation Order Recommendation
+
+1. 
+2. 
+3. 

package/templates/design/tasks/TASK_TEMPLATE.md

@@ -0,0 +1,87 @@
+---
+title: [Task Title]
+status: not-started
+mode: greenfield
+complexity: medium
+categories:
+  - backend
+affected_modules: []
+dependencies: []
+acceptance_criteria: []
+created: null
+last_updated: null
+---
+
+# Task: [Title]
+
+## Summary / Objective
+
+<!-- What this task achieves and why it is needed -->
+
+## User Story Reference
+
+<!-- Link to the user story this task supports: US-XXX -->
+
+## Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Implementation Detail
+
+### Approach
+
+<!-- How to implement this task -->
+
+### Components to Create/Modify
+
+| Component | Action | Description |
+|-----------|--------|-------------|
+|           |        |             |
+
+### Illustrative Code
+
+```typescript
+// Example interface or pseudo-code
+interface Example {
+  id: string;
+  // ...
+}
+```
+
+### API Changes
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+|          |        |             |
+
+## Testing Criteria
+
+### Unit Tests
+
+- Test case 1
+- Test case 2
+
+### Integration Tests
+
+- Integration scenario 1
+
+### Manual Tests
+
+- Manual verification step 1
+
+## Edge Cases
+
+- Edge case 1 and how it is handled
+- Edge case 2 and how it is handled
+
+## Notes
+
+<!-- Additional context, concerns, or decisions -->
+
+## Changelog
+
+| Date | Change | By |
+|------|--------|-----|
+|      |        |     |