Compare commits

...
1 Commits
Author SHA1 Message Date
OthmanAdi 539d5a3bbc Add Kiro support with native steering files (v2.10.0)
- Add .kiro/steering/ with planning-workflow.md, planning-rules.md, planning-templates.md
- Add .kiro/scripts/ with init and check-complete scripts
- Add docs/kiro.md installation guide
- Update README with Kiro badge and documentation
- Update plugin.json with Kiro keywords
- Now supports 11+ AI coding assistants

Closes #55
2026-01-26 01:40:15 +01:00
18 changed files with 677 additions and 11 deletions
+5 -2
View File
@@ -1,7 +1,7 @@
{
"name": "planning-with-files",
"version": "2.9.0",
"description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Works with Claude Code, Clawd CLI, Gemini CLI, Cursor, Continue, and 10+ AI coding assistants.",
"version": "2.10.0",
"description": "Manus-style persistent markdown files for planning, progress tracking, and knowledge storage. Works with Claude Code, Kiro, Clawd CLI, Gemini CLI, Cursor, Continue, and 11+ AI coding assistants.",
"author": {
"name": "OthmanAdi",
"url": "https://github.com/OthmanAdi"
@@ -19,6 +19,9 @@
"clawd",
"clawdbot",
"clawdhub",
"kiro",
"kiro-steering",
"amazon-kiro",
"gemini",
"cursor",
"continue",
+1 -1
View File
@@ -1,6 +1,6 @@
---
name: planning-with-files
version: "2.9.0"
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
homepage: https://github.com/OthmanAdi/planning-with-files
user-invocable: true
+1 -1
View File
@@ -1,6 +1,6 @@
---
name: planning-with-files
version: "2.9.0"
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
user-invocable: true
allowed-tools:
@@ -1,6 +1,6 @@
---
name: planning-with-files
version: "2.9.0"
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
---
+1 -1
View File
@@ -1,6 +1,6 @@
---
name: planning-with-files
version: "2.9.0"
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
user-invocable: true
allowed-tools:
@@ -1,6 +1,6 @@
---
name: planning-with-files
version: "2.9.0"
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
user-invocable: true
allowed-tools:
+42
View File
@@ -0,0 +1,42 @@
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
param(
[string]$PlanFile = "task_plan.md"
)
if (-not (Test-Path $PlanFile)) {
Write-Host "ERROR: $PlanFile not found"
Write-Host "Cannot verify completion without a task plan."
exit 1
}
Write-Host "=== Task Completion Check ==="
Write-Host ""
# Read file content
$content = Get-Content $PlanFile -Raw
# Count phases by status
$TOTAL = ([regex]::Matches($content, "### Phase")).Count
$COMPLETE = ([regex]::Matches($content, "\*\*Status:\*\* complete")).Count
$IN_PROGRESS = ([regex]::Matches($content, "\*\*Status:\*\* in_progress")).Count
$PENDING = ([regex]::Matches($content, "\*\*Status:\*\* pending")).Count
Write-Host "Total phases: $TOTAL"
Write-Host "Complete: $COMPLETE"
Write-Host "In progress: $IN_PROGRESS"
Write-Host "Pending: $PENDING"
Write-Host ""
# Check completion
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "ALL PHASES COMPLETE"
exit 0
} else {
Write-Host "TASK NOT COMPLETE"
Write-Host ""
Write-Host "Do not stop until all phases are complete."
exit 1
}
+44
View File
@@ -0,0 +1,44 @@
#!/bin/bash
# Check if all phases in task_plan.md are complete
# Exit 0 if complete, exit 1 if incomplete
# Used by Stop hook to verify task completion
PLAN_FILE="${1:-task_plan.md}"
if [ ! -f "$PLAN_FILE" ]; then
echo "ERROR: $PLAN_FILE not found"
echo "Cannot verify completion without a task plan."
exit 1
fi
echo "=== Task Completion Check ==="
echo ""
# Count phases by status (using -F for fixed string matching)
TOTAL=$(grep -c "### Phase" "$PLAN_FILE" || true)
COMPLETE=$(grep -cF "**Status:** complete" "$PLAN_FILE" || true)
IN_PROGRESS=$(grep -cF "**Status:** in_progress" "$PLAN_FILE" || true)
PENDING=$(grep -cF "**Status:** pending" "$PLAN_FILE" || true)
# Default to 0 if empty
: "${TOTAL:=0}"
: "${COMPLETE:=0}"
: "${IN_PROGRESS:=0}"
: "${PENDING:=0}"
echo "Total phases: $TOTAL"
echo "Complete: $COMPLETE"
echo "In progress: $IN_PROGRESS"
echo "Pending: $PENDING"
echo ""
# Check completion
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "ALL PHASES COMPLETE"
exit 0
else
echo "TASK NOT COMPLETE"
echo ""
echo "Do not stop until all phases are complete."
exit 1
fi
+120
View File
@@ -0,0 +1,120 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [project-name]
param(
[string]$ProjectName = "project"
)
$DATE = Get-Date -Format "yyyy-MM-dd"
Write-Host "Initializing planning files for: $ProjectName"
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
@"
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
Write-Host "Created task_plan.md"
} else {
Write-Host "task_plan.md already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
@"
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
Write-Host "Created findings.md"
} else {
Write-Host "findings.md already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
@"
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
Write-Host "Created progress.md"
} else {
Write-Host "progress.md already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
+120
View File
@@ -0,0 +1,120 @@
#!/bin/bash
# Initialize planning files for a new session
# Usage: ./init-session.sh [project-name]
set -e
PROJECT_NAME="${1:-project}"
DATE=$(date +%Y-%m-%d)
echo "Initializing planning files for: $PROJECT_NAME"
# Create task_plan.md if it doesn't exist
if [ ! -f "task_plan.md" ]; then
cat > task_plan.md << 'EOF'
# Task Plan: [Brief Description]
## Goal
[One sentence describing the end state]
## Current Phase
Phase 1
## Phases
### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints
- [ ] Document in findings.md
- **Status:** in_progress
### Phase 2: Planning & Structure
- [ ] Define approach
- [ ] Create project structure
- **Status:** pending
### Phase 3: Implementation
- [ ] Execute the plan
- [ ] Write to files before executing
- **Status:** pending
### Phase 4: Testing & Verification
- [ ] Verify requirements met
- [ ] Document test results
- **Status:** pending
### Phase 5: Delivery
- [ ] Review outputs
- [ ] Deliver to user
- **Status:** pending
## Decisions Made
| Decision | Rationale |
|----------|-----------|
## Errors Encountered
| Error | Resolution |
|-------|------------|
EOF
echo "Created task_plan.md"
else
echo "task_plan.md already exists, skipping"
fi
# Create findings.md if it doesn't exist
if [ ! -f "findings.md" ]; then
cat > findings.md << 'EOF'
# Findings & Decisions
## Requirements
-
## Research Findings
-
## Technical Decisions
| Decision | Rationale |
|----------|-----------|
## Issues Encountered
| Issue | Resolution |
|-------|------------|
## Resources
-
EOF
echo "Created findings.md"
else
echo "findings.md already exists, skipping"
fi
# Create progress.md if it doesn't exist
if [ ! -f "progress.md" ]; then
cat > progress.md << EOF
# Progress Log
## Session: $DATE
### Current Status
- **Phase:** 1 - Requirements & Discovery
- **Started:** $DATE
### Actions Taken
-
### Test Results
| Test | Expected | Actual | Status |
|------|----------|--------|--------|
### Errors
| Error | Resolution |
|-------|------------|
EOF
echo "Created progress.md"
else
echo "progress.md already exists, skipping"
fi
echo ""
echo "Planning files initialized!"
echo "Files: task_plan.md, findings.md, progress.md"
+71
View File
@@ -0,0 +1,71 @@
# Planning Rules
Critical rules for effective file-based planning.
## Rule 1: Create Plan First
Never start a complex task without `task_plan.md`. Non-negotiable.
## Rule 2: The 2-Action Rule
After every 2 view/browser/search operations, IMMEDIATELY save key findings to `findings.md`.
This prevents visual/multimodal information from being lost.
## Rule 3: Read Before Decide
Before major decisions, read `task_plan.md`. This keeps goals in your attention window.
## Rule 4: Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified
## Rule 5: Log ALL Errors
Every error goes in the plan file with this format:
```markdown
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```
## Rule 6: Never Repeat Failures
If an action failed, the next action must be different. Track what you tried and mutate the approach.
## The 3-Strike Error Protocol
```
ATTEMPT 1: Diagnose & Fix
→ Read error carefully
→ Identify root cause
→ Apply targeted fix
ATTEMPT 2: Alternative Approach
→ Same error? Try different method
→ NEVER repeat exact same failing action
ATTEMPT 3: Broader Rethink
→ Question assumptions
→ Search for solutions
→ Consider updating the plan
AFTER 3 FAILURES: Escalate to User
```
## Read vs Write Decision Matrix
| Situation | Action | Reason |
|-----------|--------|--------|
| Just wrote a file | DON'T read | Content still in context |
| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |
| Browser returned data | Write to file | Screenshots don't persist |
| Starting new phase | Read plan/findings | Re-orient if context stale |
| Error occurred | Read relevant file | Need current state to fix |
| Resuming after gap | Read all planning files | Recover state |
+88
View File
@@ -0,0 +1,88 @@
# Planning File Templates
Copy these templates to your project root when starting complex tasks.
## task_plan.md Template
```markdown
# Task Plan
## Goal
[One sentence describing the end state]
## Current Phase
Phase X: [Name] - [Status]
## Phases
### Phase 1: [Name]
**Status:** pending | in_progress | complete
- [ ] Step 1
- [ ] Step 2
### Phase 2: [Name]
**Status:** pending
- [ ] Step 1
- [ ] Step 2
## Key Questions
- Question 1?
- Question 2?
## Decisions Made
| Decision | Rationale | Date |
|----------|-----------|------|
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
```
## findings.md Template
```markdown
# Findings
## Requirements
- Requirement 1
- Requirement 2
## Research Findings
### [Topic 1]
- Finding 1
- Finding 2
## Technical Decisions
| Decision | Options Considered | Chosen | Why |
|----------|-------------------|--------|-----|
## Resources
- [Resource 1](url)
- [Resource 2](url)
```
## progress.md Template
```markdown
# Progress Log
## Session: [Date]
**Phase:** [Current phase]
**Start Time:** [Time]
### Actions Taken
1. Action 1
2. Action 2
### Files Modified
- `file1.js` — Added feature X
- `file2.py` — Fixed bug Y
### Test Results
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
### Error Log
| Time | Error | Attempt | Resolution |
|------|-------|---------|------------|
```
+43
View File
@@ -0,0 +1,43 @@
# Planning with Files Workflow
Use persistent markdown files as your "working memory on disk" — the Manus pattern that made a $2B acquisition.
## The Core Pattern
```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.
```
## Required Files
Create these three files in your project root before starting complex tasks:
| File | Purpose | When to Update |
|------|---------|----------------|
| `task_plan.md` | Phases, progress, decisions | After each phase |
| `findings.md` | Research, discoveries | After ANY discovery |
| `progress.md` | Session log, test results | Throughout session |
## Quick Start
1. **Create `task_plan.md`** with goal, phases, and status tracking
2. **Create `findings.md`** for research and technical decisions
3. **Create `progress.md`** for session logging
4. **Re-read plan before decisions** — keeps goals in attention
5. **Update after each phase** — mark complete, log errors
## When to Use This Pattern
**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls
**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups
@@ -1,6 +1,6 @@
---
name: planning-with-files
version: "2.9.0"
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
user-invocable: true
allowed-tools:
+17
View File
@@ -2,6 +2,23 @@
All notable changes to this project will be documented in this file.
## [2.10.0] - 2026-01-26
### Added
- **Kiro Support** (Issue #55 by @453783374)
- Native Kiro steering files integration
- Created `.kiro/steering/` with planning workflow, rules, and templates
- Added helper scripts in `.kiro/scripts/`
- Added `docs/kiro.md` installation guide
- Added Kiro badge to README
### Note
Kiro uses **Steering Files** (`.kiro/steering/*.md`) instead of the standard `SKILL.md` format. The steering files are automatically loaded by Kiro in every interaction.
---
## [2.9.0] - 2026-01-26
### Added
+6 -2
View File
@@ -19,7 +19,8 @@ A Claude Code plugin that transforms your workflow to use persistent markdown fi
[![Kilocode Skills](https://img.shields.io/badge/Kilocode-Skills-orange)](https://kilo.ai/docs/agent-behavior/skills)
[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-Skills-4285F4)](https://geminicli.com/docs/cli/skills/)
[![Clawd CLI](https://img.shields.io/badge/Clawd%20CLI-Skills-FF6B6B)](https://docs.clawd.bot/tools/skills)
[![Version](https://img.shields.io/badge/version-2.9.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
[![Kiro](https://img.shields.io/badge/Kiro-Steering-00D4AA)](https://kiro.dev/docs/cli/steering/)
[![Version](https://img.shields.io/badge/version-2.10.0-brightgreen)](https://github.com/OthmanAdi/planning-with-files/releases)
[![SkillCheck Validated](https://img.shields.io/badge/SkillCheck-Validated-4c1)](https://getskillcheck.com)
## Quick Install
@@ -56,6 +57,7 @@ See [docs/installation.md](docs/installation.md) for all installation methods.
| Claude Code | ✅ Full Support | [Installation](docs/installation.md) | Plugin + SKILL.md |
| Gemini CLI | ✅ Full Support | [Gemini Setup](docs/gemini.md) | Agent Skills |
| Clawd CLI | ✅ Full Support | [Clawd Setup](docs/clawd.md) | Workspace/Local Skills |
| Kiro | ✅ Full Support | [Kiro Setup](docs/kiro.md) | Steering Files |
| Cursor | ✅ Full Support | [Cursor Setup](docs/cursor.md) | Skills |
| Continue | ✅ Full Support | [Continue Setup](docs/continue.md) | Skills + Prompt files |
| Kilocode | ✅ Full Support | [Kilocode Setup](docs/kilocode.md) | Skills |
@@ -76,6 +78,7 @@ See [docs/installation.md](docs/installation.md) for all installation methods.
| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
| [Gemini CLI Setup](docs/gemini.md) | Google Gemini CLI integration guide |
| [Clawd CLI Setup](docs/clawd.md) | Clawd CLI integration guide |
| [Kiro Setup](docs/kiro.md) | Kiro steering files integration |
| [Cursor Setup](docs/cursor.md) | Cursor IDE-specific instructions |
| [Continue Setup](docs/continue.md) | Continue integration guide (skills + slash prompt) |
| [Windows Setup](docs/windows.md) | Windows-specific notes |
@@ -89,7 +92,8 @@ See [docs/installation.md](docs/installation.md) for all installation methods.
| Version | Features | Install |
|---------|----------|---------|
| **v2.9.0** (current) | Clawd CLI support | `claude plugins install OthmanAdi/planning-with-files` |
| **v2.10.0** (current) | Kiro steering files support | `claude plugins install OthmanAdi/planning-with-files` |
| **v2.9.0** | Clawd CLI support | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.8.0** | Continue IDE support, POSIX sh compatibility fix | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.7.1** | Dynamic Python detection fix | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
| **v2.7.0** | Gemini CLI support | See [releases](https://github.com/OthmanAdi/planning-with-files/releases) |
+114
View File
@@ -0,0 +1,114 @@
# Kiro Setup
How to use planning-with-files with [Kiro](https://kiro.dev).
---
## Important: Kiro Uses Steering Files
Kiro doesn't use the standard `SKILL.md` format. Instead, it uses **Steering Files** — markdown documents in `.kiro/steering/` that provide persistent project knowledge.
See: [Kiro Steering Docs](https://kiro.dev/docs/cli/steering/)
---
## What This Integration Adds
```
.kiro/
├── steering/
│ ├── planning-workflow.md # Core workflow and quick start
│ ├── planning-rules.md # Critical rules and error protocols
│ └── planning-templates.md # Templates for task_plan, findings, progress
└── scripts/
├── init-session.sh # Initialize planning files (Bash)
├── init-session.ps1 # Initialize planning files (PowerShell)
├── check-complete.sh # Verify phases complete (Bash)
└── check-complete.ps1 # Verify phases complete (PowerShell)
```
---
## Installation (Workspace)
Copy to your project:
```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
cp -r planning-with-files/.kiro .kiro
rm -rf planning-with-files
```
---
## Installation (Global)
Copy to your global Kiro config:
```bash
git clone https://github.com/OthmanAdi/planning-with-files.git
mkdir -p ~/.kiro/steering ~/.kiro/scripts
cp planning-with-files/.kiro/steering/* ~/.kiro/steering/
cp planning-with-files/.kiro/scripts/* ~/.kiro/scripts/
rm -rf planning-with-files
```
Global steering applies to all your projects.
---
## Usage
1. Start Kiro in your project
2. For complex tasks, create the planning files:
```bash
# Using the init script
bash .kiro/scripts/init-session.sh
# Or manually create:
# - task_plan.md
# - findings.md
# - progress.md
```
3. The steering files automatically guide Kiro to:
- Create plans before complex tasks
- Update findings after research
- Log progress and errors
- Follow the 3-strike error protocol
---
## How Steering Works
Kiro loads steering files automatically in every interaction. The planning guidance becomes part of Kiro's project understanding without you needing to explain it each time.
| File | Purpose |
|------|---------|
| `planning-workflow.md` | Core pattern and quick start |
| `planning-rules.md` | Critical rules and error handling |
| `planning-templates.md` | Copy-paste templates |
---
## Helper Scripts
```bash
# Initialize all planning files
bash .kiro/scripts/init-session.sh
# Windows PowerShell
powershell -ExecutionPolicy Bypass -File .kiro/scripts/init-session.ps1
# Verify all phases complete
bash .kiro/scripts/check-complete.sh
```
---
## Notes
- Steering files are loaded automatically — no manual invocation needed
- Workspace steering (`.kiro/`) takes priority over global (`~/.kiro/`)
- Planning files (`task_plan.md`, etc.) go in your project root, not in `.kiro/`
+1 -1
View File
@@ -1,6 +1,6 @@
---
name: planning-with-files
version: "2.9.0"
version: "2.10.0"
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls. Now with automatic session recovery after /clear.
user-invocable: true
allowed-tools: