@jadeit/forge-ai 0.0.0 → 1.4.0

package/skills/forge-plan/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: forge-plan
+description: Forge AI Phase 1 - Planning and requirement analysis
+license: MIT
+compatibility: opencode
+---
+
+# Forge AI: Phase 1 - Planning
+
+Invoke the `@forge-plan` agent to begin Phase 1: Planning.
+
+## What Happens
+
+1. Context is loaded (existing README/brief if present)
+2. Planning agent creates required documents:
+   - `docs/planning/project-scope.md`
+   - `docs/planning/user-stories.md`
+   - `docs/planning/implementation-plan.md`
+   - `docs/planning/technology-and-architecture.md`
+3. Agent validates all required artifacts exist
+4. State is updated in `.forge/state.yaml`
+5. You confirm transition to Phase 2
+
+## Phase 1 Outputs
+
+| Document | Purpose |
+|----------|---------|
+| project-scope.md | Project aim, high-level design, technology choices |
+| user-stories.md | User stories that drive development |
+| implementation-plan.md | High-level phases to be implemented |
+| technology-and-architecture.md | Tech choices and architecture (C4 Model) |
+
+## Constraints
+
+- NO executable code, scaffolding, or infrastructure
+- Illustrative code snippets ARE permitted
+- Use Mermaid diagrams for architecture
+
+## Flags
+
+- `--only {artifact}` - Work on specific artifact only
+  - Options: project-scope, user-stories, implementation-plan, technology
+
+## Prerequisites
+
+None — Phase 1 is the starting point.
+
+## Next Steps
+
+After Phase 1 complete, use `/forge-design` for Phase 2: Design.

package/skills/forge-quality-checker/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: forge-quality-checker
+description: Run quality gates for Forge Phase 3 - linting, type checking, security, coverage
+license: MIT
+compatibility: opencode
+metadata:
+  audience: forge-users
+  workflow: build-phase
+---
+
+# Forge Quality Checker
+
+Run quality gates for Feature Development (Phase 3).
+
+## Quality Thresholds
+
+Read from `.forge/config.yaml`:
+```yaml
+quality:
+  test_coverage_minimum: 80
+  lint_must_pass: true
+  type_check_must_pass: true
+  security_audit_must_pass: true
+```
+
+## Quality Gate Sequence
+
+Run in this order - fail fast:
+
+```
+1. Lint Check
+   ↓ (if pass)
+2. Type Check
+   ↓ (if pass)
+3. Security Audit
+   ↓ (if pass)
+4. Tests
+   ↓ (if pass)
+5. Coverage Check
+   ↓ (if pass)
+6. AI Code Review
+```
+
+## Gate Definitions
+
+### 1. Lint Check
+
+Run the project's linter:
+```bash
+# Python
+npm run lint  # or ruff, pylint, etc.
+
+# JavaScript/TypeScript
+npm run lint
+
+# Multiple
+npm run lint && npm run lint:style
+```
+
+**Gate:** Must pass (exit code 0)
+
+### 2. Type Check
+
+Run the project's type checker:
+```bash
+# TypeScript
+npx tsc --noEmit
+
+# Python
+npm run typecheck  # or mypy, pyright
+```
+
+**Gate:** Must pass (exit code 0)
+
+### 3. Security Audit
+
+Run security checks:
+```bash
+# npm
+npm audit
+
+# pip
+pip-audit
+
+# Docker
+trivy image [image-name]
+```
+
+**Gate:** Must pass (no critical/high vulnerabilities, or all acknowledged)
+
+### 4. Tests
+
+Run the test suite:
+```bash
+npm test
+# or
+pytest
+```
+
+**Gate:** All tests must pass (no failures)
+
+### 5. Coverage Check
+
+Run tests with coverage:
+```bash
+# Jest
+npm run test:coverage
+
+# pytest
+pytest --cov=. --cov-report=term-missing
+```
+
+**Gate:** Coverage >= configured minimum (default 80%)
+
+## Tool Detection
+
+Detect available tools automatically:
+
+| File | Tool |
+|------|------|
+| `package.json` | npm, jest, eslint, tsc |
+| `pyproject.toml` | pytest, ruff, mypy |
+| `Dockerfile` | hadolint, trivy |
+| `Makefile` | make targets |
+
+## Language-Specific Guidelines
+
+### Python
+
+- Use `ruff` for linting and formatting
+- Use `mypy` or `pyright` for type checking
+- Use `pytest` for testing
+- Use `bandit` for security
+
+### JavaScript/TypeScript
+
+- Use `eslint` for linting
+- Use `typescript` (tsc) for type checking
+- Use `jest` or `vitest` for testing
+- Use `npm audit` for security
+
+### Multi-language Projects
+
+Run all applicable tools:
+```bash
+# Run all checks
+npm run lint && npm run typecheck && npm test
+ruff check .
+mypy src/
+```
+
+## AI Code Review
+
+After automated checks pass, perform AI review:
+
+### SOLID Principles Check
+
+- **S**ingle Responsibility: Does each module do one thing?
+- **O**pen/Closed: Open for extension, closed for modification?
+- **L**iskov Substitution: Can subtypes replace base types?
+- **I**nterface Segregation: Are interfaces small and focused?
+- **D**ependency Inversion: Depend on abstractions?
+
+### Design Patterns Check
+
+Are established patterns used appropriately?
+- Factory, Builder, Singleton
+- Repository, Unit of Work
+- Observer, Strategy
+
+### Error Handling Check
+
+- Are errors caught and handled appropriately?
+- Are exceptions used for exceptional cases only?
+- Is error context preserved?
+
+### Security Check (Manual)
+
+- Input validation on all user inputs
+- Authentication/authorization properly enforced
+- Secrets not logged or exposed
+- SQL injection, XSS, CSRF addressed
+
+## Reporting
+
+### Pass Report
+
+```
+Quality Gates: PASSED
+
+✓ Lint Check - No issues
+✓ Type Check - No errors
+✓ Security Audit - No vulnerabilities
+✓ Tests - 42 passed, 0 failed
+✓ Coverage - 87% (threshold: 80%)
+
+AI Code Review: PASSED
+- SOLID compliance: ✓
+- Design patterns: ✓
+- Error handling: ✓
+- Security: ✓
+
+Ready to proceed.
+```
+
+### Fail Report
+
+```
+Quality Gates: FAILED
+
+✗ Lint Check - 3 issues found
+  - src/auth.ts:45 - Unused variable 'temp'
+  - src/utils.ts:12 - Line too long (85 > 80)
+  - src/api.ts:78 - Missing semicolon
+
+Fix required before proceeding.
+```
+
+## Rework Routing
+
+| Issue Type | Route To |
+|------------|----------|
+| Lint/type errors | `forge 3:build 5:implement` |
+| Test failures | `forge 3:build 5:implement` |
+| Coverage below threshold | `forge 3:build 5:implement` |
+| Design flaw | `forge 3:build 4:approach` |
+| Security vulnerability | `forge 3:build 5:implement` (critical) or `forge 3:build 4:approach` |

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-status/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: forge-status
+description: Forge AI - Diagnose and recover from state inconsistencies
+license: MIT
+compatibility: opencode
+---
+
+# Forge Status - State Recovery
+
+Diagnose and recover from Forge state inconsistencies.
+
+## What It Checks
+
+### 1. Phase Consistency
+- Verify `project_phase` matches phase_history
+- Check for orphaned phase entries
+- Validate phase transitions are logical
+
+### 2. Feature State Integrity
+- Validate all features have required fields
+- Check current_sub_phase is valid (1_discover through 8_summarise)
+- Verify task_document paths exist
+
+### 3. Task Document References
+- Verify all referenced task documents exist
+- Check for broken references
+- Validate frontmatter consistency
+
+### 4. Rework Tracking
+- Report rework loop counts
+- Warn if approaching thresholds
+
+### 5. Context Budget
+- Report context usage
+- Warn if approaching limits
+
+## Diagnostic Output Format
+
+```
+Forge Status Report
+====================
+
+Phase: 3 (Development)
+Active Features: 2
+  - auth-system: 5_implement (loops: 1/3)
+  - api-gateway: 3_clarify (loops: 0/3)
+
+Issues Found: 1
+  ⚠ WARN: docs/design/tasks/legacy-task.md references non-existent task
+```
+
+## Recovery Actions
+
+| Issue | Recovery |
+|-------|----------|
+| Missing phase history | Rebuild from artifacts |
+| Invalid sub-phase | Reset to valid state |
+| Broken task ref | Remove orphaned reference |
+| Corrupted state | Offer state reset |