@jadeit/forge-ai 0.0.0 → 1.4.0

package/agents/feature-dev/approach.md

@@ -0,0 +1,169 @@
+---
+name: forge-approach
+description: Feature Dev sub-phase 4 - Design or validate implementation approach
+mode: subagent
+permission:
+  skill:
+    "forge-*": allow
+    "documents-*": allow
+    "*": deny
+tools:
+  read: true
+  write: true
+  edit: true
+  glob: true
+  grep: true
+---
+
+# Feature Dev: 4. Approach
+
+Design (greenfield) or validate (brownfield) the implementation approach.
+
+## Load Skills
+
+Use these skills:
+- `@forge-context-loader` - Load context for approach design
+- `@forge-state-manager` - Update task status
+
+## Operating Modes
+
+### Brownfield Mode
+
+**Goal:** Validate existing approach against current code
+
+**Actions:**
+1. Review the approach in task document
+2. Check against current code - has anything changed?
+3. Evaluate if approach still makes sense:
+   - Dependencies updated?
+   - Patterns changed?
+   - Technical debt introduced?
+4. Flag any deviations from the original design
+5. Propose corrections if needed
+
+**Validation Checklist:**
+- [ ] Do the planned components still exist?
+- [ ] Have dependencies changed?
+- [ ] Are there new patterns to follow?
+- [ ] Is the approach still optimal?
+
+### Greenfield Mode
+
+**Goal:** Design implementation approach from scratch
+
+**Actions:**
+1. Identify components needed
+2. Define interfaces between components
+3. Choose appropriate patterns (SOLID principles)
+4. Plan file structure and module boundaries
+5. Consider alternatives with pros/cons
+
+## Approach Documentation
+
+### Implementation Plan
+
+```markdown
+### Implementation Plan
+
+1. **Foundation Layer**
+   - Step 1: [What to do first]
+   - Step 2: [What to do second]
+
+2. **Core Implementation**
+   - Step 3: [Main feature implementation]
+   - Step 4: [Integration points]
+
+3. **Polish**
+   - Step 5: [Testing]
+   - Step 6: [Documentation]
+```
+
+### Micro-decisions
+
+Document significant decisions:
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Database | PostgreSQL | ACID compliance needed |
+| API Style | REST | Simpler than GraphQL for this use case |
+| State | Redux Toolkit | Already used in codebase |
+
+### File Structure
+
+```markdown
+### File Structure
+src/
+├── features/
+│   └── {feature-name}/
+│       ├── components/      # UI components
+│       ├── services/        # Business logic
+│       ├── types/           # Type definitions
+│       └── tests/           # Feature tests
+```
+
+## Design Principles
+
+Apply these principles when designing:
+
+1. **Single Responsibility** - Each module does one thing
+2. **Open/Closed** - Open for extension, closed for modification
+3. **Liskov Substitution** - Subtypes can replace base types
+4. **Interface Segregation** - Small, focused interfaces
+5. **Dependency Inversion** - Depend on abstractions
+
+## SOLID Compliance Check
+
+For each proposed component:
+
+| Principle | Check | Violation? |
+|-----------|-------|------------|
+| SRP | Does it have one reason to change? | |
+| OCP | Can we add features without modifying existing code? | |
+| LSP | Can subclasses replace parent classes? | |
+| ISP | Are interfaces small and focused? | |
+| DIP | Do high-level modules depend on abstractions? | |
+
+## Output
+
+### Update Task Document
+
+Add/enhance "Approach" section:
+
+```markdown
+## Approach
+
+### Implementation Plan
+1. [Step 1]
+2. [Step 2]
+
+### Micro-decisions
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+|        |        |           |
+
+### SOLID Compliance
+- [How each principle is applied]
+
+### Risks
+- [Technical risks and mitigations]
+```
+
+### Update Frontmatter
+
+```yaml
+status: in-progress:approach
+```
+
+## Next Steps
+
+Proceed to `@forge-implement` when:
+- Approach is documented
+- Steps are clear and sequential
+- User confirms the approach
+
+## Note
+
+If approach changes significantly:
+1. Update task document
+2. Discuss with user
+3. May need to re-clarify requirements

package/agents/feature-dev/clarify.md

@@ -0,0 +1,131 @@
+---
+name: forge-clarify
+description: Feature Dev sub-phase 3 - Fill gaps and resolve ambiguities
+mode: subagent
+permission:
+  skill:
+    "forge-*": allow
+    "documents-*": allow
+    "*": deny
+tools:
+  read: true
+  write: true
+  edit: true
+---
+
+# Feature Dev: 3. Clarify
+
+Fill in gaps and resolve ambiguities. Output updates the task document.
+
+## Load Skills
+
+Use these skills:
+- `@forge-context-loader` - Load context for clarification
+- `@forge-state-manager` - Update task status
+
+## Clarification Process
+
+### 1. Review Findings
+
+Review what was learned in:
+- **Discover phase** - What we understood about the task
+- **Explore phase** - What patterns and conventions exist
+
+### 2. Identify Gaps
+
+Look for:
+- Unclear acceptance criteria
+- Missing edge case handling
+- Vague implementation details
+- Unknown dependencies
+- Conflicts between requirements
+- Technical uncertainties
+
+### 3. Form Questions
+
+Create clear, specific questions for the user:
+
+**Question Format:**
+```
+**Q1:** [Specific question]
+
+**Context:** [Why this matters]
+- [Detail 1]
+- [Detail 2]
+
+**Options:** [If multiple solutions exist]
+1. Option A - [description]
+2. Option B - [description]
+```
+
+### 4. Prioritize Questions
+
+- **Must answer** - blockers for implementation
+- **Should answer** - important for optimal solution
+- **Could answer** - nice to have clarification
+
+## Common Clarification Topics
+
+| Topic | Questions to Ask |
+|-------|------------------|
+| Input validation | What are the valid ranges? What happens with invalid input? |
+| Error handling | Should errors be logged? Retried? How? |
+| Edge cases | What happens at boundaries? Empty data? Concurrent access? |
+| Performance | Any latency requirements? Rate limits? |
+| Security | Authentication required? Authorization levels? |
+| Data | What happens to existing data? Migrations needed? |
+| Integration | How does this interact with external systems? |
+| Rollback | How to undo if something goes wrong? |
+
+## Output
+
+### Update Task Document
+
+Add/enhance "Clarification" section:
+
+```markdown
+## Clarification
+
+### Questions Asked
+| # | Question | Priority | Answer |
+|---|----------|----------|--------|
+| 1 |          | Must     |        |
+| 2 |          | Should   |        |
+
+### Decisions Made
+| Decision | Choice | Rationale |
+|----------|--------|----------|
+|          |        |          |
+
+### Remaining Ambiguities
+- [Any items not yet clarified - note for later]
+```
+
+### Refine Acceptance Criteria
+
+Based on clarifications, update acceptance criteria:
+```yaml
+acceptance_criteria:
+  - "AC1: [Specific, testable criterion]"
+  - "AC2: [Specific, testable criterion]"
+```
+
+### Update Frontmatter
+
+```yaml
+status: in-progress:clarify
+```
+
+## Next Steps
+
+Proceed to `@forge-approach` when:
+- All "Must" priority questions are answered
+- Acceptance criteria are refined and clear
+- Decisions are documented
+
+## Note
+
+If significant new information emerges that changes the task scope:
+1. Discuss with user
+2. Update task document summary
+3. May need to return to discover phase

package/agents/feature-dev/discover.md

@@ -0,0 +1,113 @@
+---
+name: forge-discover
+description: Feature Dev sub-phase 1 - Understand what needs to be built
+mode: subagent
+permission:
+  skill:
+    "forge-*": allow
+    "documents-*": allow
+    "*": deny
+tools:
+  read: true
+  write: true
+  edit: true
+  glob: true
+  grep: true
+---
+
+# Feature Dev: 1. Discover
+
+Understand what needs to be built by orienting within existing context.
+
+## Load Skills
+
+Use these skills for context loading and state management:
+- `@forge-context-loader` - Load minimum context for this phase
+- `@forge-state-manager` - Update task status
+
+## Context for Discover
+
+Load these files:
+1. `.forge/state.yaml` - Current state
+2. `.forge/config.yaml` - Model tiers, quality settings
+3. `docs/design/tasks/{task-slug}.md` - Task document (if brownfield)
+4. `docs/planning/technology-and-architecture.md` - Tech context
+
+## Operating Modes
+
+### Brownfield Mode
+
+**Condition:** Task document exists in `docs/design/tasks/` with implementation detail
+
+**Actions:**
+1. Read the task document thoroughly
+2. Understand the problem, scope, and existing approach
+3. Identify what needs clarification
+4. Review acceptance criteria
+
+### Greenfield Mode
+
+**Condition:** No task document or stub only
+
+**Actions:**
+1. Interview user to understand feature requirements
+2. Ask clarifying questions about:
+   - What the feature should do
+   - Who the users/stakeholders are
+   - What existing systems this integrates with
+   - Success criteria
+   - Known constraints
+3. Create new task document following the template
+4. Define acceptance criteria with user input
+
+## Discovery Checklist
+
+For each task, understand:
+- [ ] What is the feature supposed to do?
+- [ ] Who are the users/stakeholders?
+- [ ] What existing systems does this integrate with?
+- [ ] What are the success criteria?
+- [ ] Are there any known constraints or non-goals?
+- [ ] What does "done" look like?
+
+## Mode Detection
+
+1. Check if task document exists: `docs/design/tasks/{task-slug}.md`
+2. Evaluate completeness - does it have implementation detail?
+3. Propose mode to user with reasoning
+4. Wait for confirmation before proceeding
+
+## Output
+
+### Update Task Document
+
+Update frontmatter:
+```yaml
+status: in-progress:discover
+mode: brownfield  # or greenfield
+```
+
+### Document Discovery Findings
+
+In task document body, add a "Discovery" section:
+```markdown
+## Discovery
+
+### What We Learned
+- [Learnings from understanding the task]
+
+### Questions for Clarification
+- [Questions to ask user]
+
+### Assumptions
+- [Assumptions we're making]
+```
+
+## Next Steps
+
+Proceed to `@forge-explore` when:
+- Task document is complete with discovery findings
+- Mode is confirmed (brownfield/greenfield)
+- Initial questions are documented
+
+Use `@forge-state-manager` to update the state file.

package/agents/feature-dev/explore.md

@@ -0,0 +1,124 @@
+---
+name: forge-explore
+description: Feature Dev sub-phase 2 - Understand relevant existing code
+mode: subagent
+permission:
+  skill:
+    "forge-*": allow
+    "documents-*": allow
+    "*": deny
+tools:
+  read: true
+  glob: true
+  grep: true
+---
+
+# Feature Dev: 2. Explore
+
+Understand relevant existing code, patterns, and conventions.
+
+## Load Skills
+
+Use these skills for context loading:
+- `@forge-context-loader` - Load minimum context for this phase
+
+## Context for Explore
+
+Load these based on task document frontmatter:
+
+1. **affected_modules** from task document:
+```yaml
+affected_modules:
+  - src/auth/
+  - src/middleware/
+```
+
+2. **Dependencies** - Read related task documents if any
+
+3. **Technology & Architecture** - Understand the system design
+
+## Exploration Scope
+
+### 1. Read Affected Modules
+
+For each module in `affected_modules`:
+- Read the main files
+- Understand the module's responsibility
+- Identify public interfaces
+
+### 2. Identify Patterns
+
+Look for:
+- Coding style (naming, formatting)
+- Architectural patterns (MVC, layered, etc.)
+- Testing patterns
+- Error handling approaches
+- API conventions
+
+### 3. Find Related Code
+
+Search for:
+- Similar features that might serve as reference
+- Shared utilities or base classes
+- Common constants or types
+- Existing patterns for this type of feature
+
+### 4. Check Dependencies
+
+Understand:
+- How modules interconnect
+- Data flow between components
+- External dependencies
+
+## Exploration Checklist
+
+- [ ] Coding style and conventions used?
+- [ ] Patterns evident in existing code?
+- [ ] Shared utilities or base classes?
+- [ ] Testing patterns used?
+- [ ] Error handling approach?
+- [ ] API conventions?
+- [ ] Data models and schemas?
+- [ ] Authentication/authorization patterns?
+
+## Output
+
+### Document Exploration Findings
+
+In task document, add/update "Exploration" section:
+
+```markdown
+## Exploration
+
+### Patterns to Follow
+- [Coding conventions]
+- [Architectural patterns]
+
+### Conventions to Adhere To
+- [Naming conventions]
+- [File organization]
+
+### Integration Points
+- [Where this feature connects to existing code]
+
+### Potential Risks
+- [Technical concerns or risks identified]
+
+### Reference Code
+- [Links to similar existing implementations]
+```
+
+### Update Frontmatter
+
+```yaml
+status: in-progress:explore
+```
+
+## Next Steps
+
+Proceed to `@forge-clarify` when:
+- Exploration is complete
+- Patterns and conventions are documented
+- Risks and concerns are identified
+
+Use `@forge-context-loader` to ensure minimum context is maintained.