plan-flow-skill 1.0.0

package/skills/plan-flow/discovery/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: discovery
+description: Create a discovery document to gather and clarify requirements
+metadata: {"openclaw":{"requires":{"bins":["git"]}}}
+user-invocable: true
+---
+
+# Discovery
+
+Create a discovery document for gathering and clarifying requirements before creating an implementation plan.
+
+## What It Does
+
+1. Gathers functional and non-functional requirements
+2. Documents constraints and dependencies
+3. Identifies open questions that need answers
+4. Proposes a high-level approach
+5. Documents risks and unknowns
+
+## Usage
+
+```
+/discovery <topic>
+```
+
+**Arguments:**
+- `topic` (required): The feature or topic to discover requirements for
+
+## Output
+
+Creates: `flow/discovery/discovery_<topic>_v<version>.md`
+
+## Document Structure
+
+```markdown
+# Discovery: [Topic]
+
+## Context
+Why this discovery is needed
+
+## Requirements Gathered
+### Functional Requirements
+- [FR-1]: Description
+
+### Non-Functional Requirements
+- [NFR-1]: Description
+
+### Constraints
+- [C-1]: Description
+
+## Open Questions
+| # | Question | Status | Answer |
+|---|----------|--------|--------|
+| 1 | Question | Open   | -      |
+
+## Technical Considerations
+Architecture, dependencies, patterns
+
+## Proposed Approach
+High-level recommendation
+
+## Risks and Unknowns
+Identified risks with mitigation strategies
+
+## Next Steps
+Follow-up actions
+```
+
+## Example
+
+```
+/discovery user authentication with OAuth
+```
+
+**Creates:** `flow/discovery/discovery_user_authentication_with_oauth_v1.md`
+
+## Critical Rules
+
+- **No Code**: Discovery is for gathering requirements only. No implementation.
+- **Ask Questions**: Use interactive questions to clarify unclear requirements.
+- **Mark Assumptions**: Always explicitly mark assumptions for validation.
+
+## Next Command
+
+After discovery, run `/create-plan @flow/discovery/discovery_<topic>_v1.md` to create an implementation plan.

package/skills/plan-flow/execute-plan/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: execute-plan
+description: Execute phases from an implementation plan
+metadata: {"openclaw":{"requires":{"bins":["git"]}}}
+user-invocable: true
+---
+
+# Execute Plan
+
+Execute phases from an implementation plan, following complexity-based grouping.
+
+## What It Does
+
+1. Reads the plan file and identifies phases
+2. Groups phases based on complexity scores
+3. Presents phase details before implementation
+4. Implements each phase following project patterns
+5. Marks tasks as complete
+6. Runs build verification
+
+## Usage
+
+```
+/execute-plan <plan_file> [phase]
+```
+
+**Arguments:**
+- `plan_file` (required): Path to the plan file
+- `phase` (optional): Phase number, range, or "next". Default: next incomplete phase
+
+**Phase Options:**
+- `1` - Execute phase 1
+- `1-3` - Execute phases 1 through 3
+- `next` - Execute next incomplete phase
+- `all` - Execute all remaining phases
+
+## Execution Strategy
+
+Based on combined complexity scores:
+
+| Combined Score | Strategy |
+|----------------|----------|
+| ≤ 6 | **Aggregate**: Execute multiple phases together |
+| 7-10 | **Cautious**: Execute 1-2 phases, then verify |
+| > 10 | **Sequential**: Execute one phase at a time |
+
+## Phase Execution Flow
+
+For each phase:
+
+1. **Present**: Show phase details and approach
+2. **Implement**: Write code following project patterns
+3. **Update**: Mark tasks complete in plan file
+4. **Verify**: Run build verification
+
+## Example
+
+```
+/execute-plan @flow/plans/plan_user_auth_v1.md phase:1
+```
+
+**Output:**
+```
+Executing Phase 1: Types and Schemas
+Complexity: 3/10
+
+Tasks:
+- [ ] Create User type definitions
+- [ ] Create Zod validation schemas
+
+Implementing...
+
+✓ Phase 1 Complete
+- Created src/types/user.ts
+- Created src/schemas/user.ts
+
+Build verification: npm run build ✓
+```
+
+## Critical Rules
+
+- **Follow Patterns**: Always follow existing project patterns
+- **Build After Each Phase**: Verify build passes before proceeding
+- **Update Plan**: Mark completed tasks in the plan file
+- **Tests Last**: Execute test phase only after all other phases complete
+
+## Next Command
+
+After executing all phases, run `/review-code` to review your changes before committing.

package/skills/plan-flow/review-code/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: review-code
+description: Review local uncommitted code changes
+metadata: {"openclaw":{"requires":{"bins":["git"]}}}
+user-invocable: true
+---
+
+# Review Code
+
+Review local uncommitted changes in the repository.
+
+## What It Does
+
+1. Gets git diff of changes (staged, unstaged, or all)
+2. Identifies changed files and their patterns
+3. Finds similar implementations in the codebase
+4. Reviews against project patterns and rules
+5. Provides findings with severity and fix suggestions
+6. Generates a review document
+
+## Usage
+
+```
+/review-code [path] [scope]
+```
+
+**Arguments:**
+- `path` (optional): Specific file or directory to review
+- `scope` (optional): `staged`, `unstaged`, or `all` (default: all)
+
+## Output
+
+Creates: `flow/reviewed-code/review_<scope>.md`
+
+## Review Categories
+
+| Severity | Description | Action Required |
+|----------|-------------|-----------------|
+| Critical | Security issues, major bugs | Must fix before commit |
+| Major | Significant problems | Should fix |
+| Minor | Code quality issues | Consider fixing |
+| Suggestion | Improvements | Optional |
+
+## Review Document Structure
+
+```markdown
+# Code Review: [Scope]
+
+## Review Information
+| Field | Value |
+|-------|-------|
+| Date | YYYY-MM-DD |
+| Files Reviewed | N |
+| Scope | all/staged/unstaged |
+
+## Changed Files
+| File | Status | Lines Changed |
+|------|--------|---------------|
+| path/to/file | modified | +10/-5 |
+
+## Findings
+
+### Finding 1: [Name]
+| Field | Value |
+|-------|-------|
+| File | path/to/file |
+| Line | 42 |
+| Severity | Major |
+| Fix Complexity | 3/10 |
+
+**Description**: What's wrong
+**Suggested Fix**: How to fix it
+
+## Commit Readiness
+| Status | Ready to Commit / Needs Changes |
+```
+
+## Example
+
+```
+/review-code
+```
+
+**Scoped review:**
+```
+/review-code src/components staged
+```
+
+## What It Checks
+
+- Pattern consistency with existing codebase
+- Error handling completeness
+- Type safety (for TypeScript)
+- Security concerns (hardcoded secrets, injection risks)
+- Performance considerations
+- Code organization and naming
+
+## Next Command
+
+After fixing issues, commit your changes or run `/review-pr` after creating a PR.

package/skills/plan-flow/review-pr/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: review-pr
+description: Review a Pull Request
+metadata: {"openclaw":{"requires":{"bins":["git","gh"]}}}
+user-invocable: true
+---
+
+# Review PR
+
+Review a Pull Request by its number using the GitHub CLI.
+
+## What It Does
+
+1. Fetches PR information using `gh pr view`
+2. Gets PR diff using `gh pr diff`
+3. Analyzes changes against project patterns
+4. Checks for security and performance issues
+5. Provides detailed findings and recommendations
+6. Generates a review document
+
+## Usage
+
+```
+/review-pr <pr_number>
+```
+
+**Arguments:**
+- `pr_number` (required): The PR number to review
+
+## Prerequisites
+
+- `gh` CLI must be installed and authenticated
+- Run `gh auth login` if not authenticated
+
+## Output
+
+Creates: `flow/reviewed-pr/pr_<number>.md`
+
+## Review Focus Areas
+
+| Area | What's Checked |
+|------|----------------|
+| Code Quality | Pattern consistency, naming, organization |
+| Security | Secrets, injection, authentication |
+| Performance | N+1 queries, unnecessary loops, caching |
+| Testing | Test coverage, edge cases |
+| Documentation | Comments, README updates |
+
+## Review Document Structure
+
+```markdown
+# PR Review: #<number>
+
+## PR Information
+| Field | Value |
+|-------|-------|
+| Title | PR title |
+| Author | username |
+| Branch | feature -> main |
+| Files Changed | N |
+
+## Summary
+What this PR does
+
+## Findings
+
+### Finding 1: [Name]
+| Field | Value |
+|-------|-------|
+| File | path/to/file |
+| Severity | Major |
+
+**Description**: What's wrong
+**Suggested Fix**: How to fix it
+
+## Security Considerations
+Any security concerns
+
+## Performance Considerations
+Any performance concerns
+
+## Recommendation
+| Status | Approve / Request Changes / Comment |
+```
+
+## Example
+
+```
+/review-pr 123
+```
+
+**Output:**
+```
+Reviewing PR #123...
+
+Fetching PR information...
+Fetching PR diff...
+Analyzing changes...
+
+PR #123 Review Complete!
+
+Summary: Adds user authentication with OAuth
+Files Changed: 12
+Findings: 2 Major, 3 Minor
+
+Review saved to: flow/reviewed-pr/pr_123.md
+
+Recommendation: Request Changes
+- Fix the 2 major issues before merging
+```
+
+## Authentication
+
+If you get authentication errors:
+
+```bash
+# Authenticate with GitHub
+gh auth login
+
+# Verify authentication
+gh auth status
+```

package/skills/plan-flow/setup/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: setup
+description: Analyze project structure and create Plan-Flow configuration
+metadata: {"openclaw":{"requires":{"bins":["git"]}}}
+user-invocable: true
+---
+
+# Setup
+
+Analyze the current repository and generate Plan-Flow configuration files.
+
+## What It Does
+
+1. Scans project structure to detect languages and frameworks
+2. Creates the `flow/` directory structure
+3. Identifies existing patterns in the codebase
+4. Generates initial configuration
+
+## Usage
+
+```
+/setup [path]
+```
+
+**Arguments:**
+- `path` (optional): Directory to analyze. Defaults to current directory.
+
+## Output
+
+Creates the following structure:
+
+```
+flow/
+├── archive/           # Completed/abandoned plans
+├── contracts/         # Integration contracts
+├── discovery/         # Discovery documents
+├── plans/             # Active implementation plans
+├── references/        # Reference materials
+├── reviewed-code/     # Code review documents
+└── reviewed-pr/       # PR review documents
+```
+
+## Example
+
+```
+/setup
+```
+
+**Output:**
+```
+Setup Complete!
+
+Analyzed: /path/to/project
+Files found: 156
+Languages detected: TypeScript, JavaScript
+Frameworks detected: Next.js, Jest
+
+Created Directories:
+- flow/discovery/
+- flow/plans/
+- flow/contracts/
+- flow/references/
+- flow/archive/
+
+Next Steps:
+1. Create .plan-flow.yml with your AI API key
+2. Run /discovery to gather requirements for a feature
+3. Run /create-plan to create an implementation plan
+```
+
+## Next Command
+
+After setup, run `/discovery` to start gathering requirements for a new feature.

package/skills/plan-flow/write-tests/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: write-tests
+description: Generate tests to achieve coverage targets
+metadata: {"openclaw":{"requires":{"bins":["git"]}}}
+user-invocable: true
+---
+
+# Write Tests
+
+Generate tests for specified code to achieve coverage targets.
+
+## What It Does
+
+1. Reads the target file(s)
+2. Analyzes functions and classes to test
+3. Identifies edge cases and error scenarios
+4. Generates comprehensive test file(s)
+5. Follows project testing patterns
+
+## Usage
+
+```
+/write-tests <path> [coverage]
+```
+
+**Arguments:**
+- `path` (required): File or directory to generate tests for
+- `coverage` (optional): Target coverage percentage (default: 80)
+
+## Output
+
+Creates test files following project conventions:
+- `*.test.ts` for TypeScript
+- `*.test.js` for JavaScript
+- `test_*.py` for Python
+
+## Test Coverage
+
+| Coverage | Description |
+|----------|-------------|
+| 80% | Standard target (default) |
+| 90% | High coverage for critical code |
+| 100% | Complete coverage (edge cases included) |
+
+## What Gets Tested
+
+- **Exported Functions**: All public functions
+- **Classes**: Constructor, public methods
+- **Edge Cases**: Null, undefined, empty, boundary values
+- **Error Scenarios**: Exception handling, validation errors
+- **Async Code**: Promise resolution/rejection
+
+## Test Structure (TypeScript/Jest)
+
+```typescript
+describe('FunctionName', () => {
+  beforeEach(() => {
+    // Setup
+  });
+
+  it('should handle normal input', () => {
+    // Arrange
+    // Act
+    // Assert
+  });
+
+  it('should handle edge case', () => {
+    // Test edge case
+  });
+
+  it('should throw error for invalid input', () => {
+    expect(() => fn(invalid)).toThrow();
+  });
+});
+```
+
+## Example
+
+```
+/write-tests src/utils/validator.ts 90
+```
+
+**Output:**
+```
+Generating tests for src/utils/validator.ts
+Target coverage: 90%
+
+Analyzing functions:
+- validateEmail() - 3 test cases
+- validatePassword() - 5 test cases
+- validateUsername() - 4 test cases
+
+Generated: src/utils/validator.test.ts
+
+Test Summary:
+- 12 test cases generated
+- Estimated coverage: 92%
+
+Run tests with: npm run test src/utils/validator.test.ts
+```
+
+## Test Patterns
+
+The skill follows testing patterns from your project:
+
+- **Jest** for JavaScript/TypeScript
+- **Pytest** for Python
+- Uses existing mock factories if available
+- Follows AAA pattern (Arrange, Act, Assert)
+
+## Next Command
+
+After generating tests, run them with your test runner:
+- `npm run test` for Jest
+- `pytest` for Python

package/templates/shared/AGENTS.md.template

@@ -0,0 +1,60 @@
+# Plan-Flow: Structured AI-Assisted Development
+
+## Quick Start
+
+| Command | Purpose |
+|---------|---------|
+| `/setup` | Analyze project and generate pattern files |
+| `/discovery-plan` | Create discovery document for requirements gathering |
+| `/create-plan` | Create implementation plan with phases and complexity scores |
+| `/execute-plan` | Execute plan phases with verification |
+| `/create-contract` | Create integration contract from API docs |
+| `/review-code` | Review local uncommitted changes |
+| `/review-pr` | Review a Pull Request |
+| `/write-tests` | Write tests to achieve coverage target |
+
+## Recommended Workflow
+
+1. `/setup` - Run once to index project patterns
+2. `/discovery-plan` - Gather requirements for a new feature
+3. `/create-plan` - Create structured implementation plan
+4. `/execute-plan` - Execute the plan phase by phase
+5. `/review-code` or `/review-pr` - Review changes before merging
+
+## Critical Rules
+
+1. **No Auto-Chaining**: Never auto-invoke the next command. Wait for user.
+2. **Discovery First**: Recommend `/discovery-plan` before `/create-plan` for new features.
+3. **Tests Last**: Tests are always the last phase of any implementation plan.
+4. **Build at End Only**: Run `npm run build` only after ALL phases complete.
+
+## Flow Directory Structure
+
+```
+flow/
+├── archive/           # Completed/abandoned plans
+├── contracts/         # Integration contracts
+├── discovery/         # Discovery documents
+├── plans/             # Active implementation plans
+├── references/        # Reference materials
+├── reviewed-code/     # Code review documents
+└── reviewed-pr/       # PR review documents
+```
+
+## Complexity Scoring
+
+Every plan phase has a complexity score (0-10):
+
+| Score | Level | Description |
+|-------|-------|-------------|
+| 0-2 | Trivial | Simple, mechanical changes |
+| 3-4 | Low | Straightforward implementation |
+| 5-6 | Medium | Moderate complexity, some decisions |
+| 7-8 | High | Complex, multiple considerations |
+| 9-10 | Very High | Significant complexity/risk |
+
+## Skills
+
+Plan-flow skills are in `.agents/skills/plan-flow/`:
+- Each skill has a `SKILL.md` with frontmatter and instructions
+- Use the skill names as slash commands

package/templates/shared/CLAUDE.md.template

@@ -0,0 +1,62 @@
+# Plan-Flow: Structured AI-Assisted Development
+
+## Quick Start
+
+| Command | Purpose |
+|---------|---------|
+| `/setup` | Analyze project and generate pattern files |
+| `/discovery-plan` | Create discovery document for requirements gathering |
+| `/create-plan` | Create implementation plan with phases and complexity scores |
+| `/execute-plan` | Execute plan phases with verification |
+| `/create-contract` | Create integration contract from API docs |
+| `/review-code` | Review local uncommitted changes |
+| `/review-pr` | Review a Pull Request |
+| `/write-tests` | Write tests to achieve coverage target |
+
+## Recommended Workflow
+
+1. `/setup` - Run once to index project patterns
+2. `/discovery-plan` - Gather requirements for a new feature
+3. `/create-plan` - Create structured implementation plan
+4. `/execute-plan` - Execute the plan phase by phase
+5. `/review-code` or `/review-pr` - Review changes before merging
+
+## Critical Rules
+
+1. **No Auto-Chaining**: Never auto-invoke the next command. Wait for user.
+2. **Discovery First**: Recommend `/discovery-plan` before `/create-plan` for new features.
+3. **Tests Last**: Tests are always the last phase of any implementation plan.
+4. **Build at End Only**: Run `npm run build` only after ALL phases complete.
+
+## Flow Directory Structure
+
+```
+flow/
+├── archive/           # Completed/abandoned plans
+├── contracts/         # Integration contracts
+├── discovery/         # Discovery documents
+├── plans/             # Active implementation plans
+├── references/        # Reference materials
+├── reviewed-code/     # Code review documents
+└── reviewed-pr/       # PR review documents
+```
+
+## Complexity Scoring
+
+Every plan phase has a complexity score (0-10):
+
+| Score | Level | Description |
+|-------|-------|-------------|
+| 0-2 | Trivial | Simple, mechanical changes |
+| 3-4 | Low | Straightforward implementation |
+| 5-6 | Medium | Moderate complexity, some decisions |
+| 7-8 | High | Complex, multiple considerations |
+| 9-10 | Very High | Significant complexity/risk |
+
+## Rules
+
+Pattern rules are in `.claude/rules/`:
+- `core/` - Allowed patterns, forbidden patterns, complexity scoring
+- `patterns/` - Templates and patterns for plans, discovery, contracts
+- `languages/` - Language-specific patterns (TypeScript, Python)
+- `tools/` - Tool-specific patterns (Jest, Pytest, auth)