{"id":39656779,"url":"https://github.com/chenmudu/spec-workflow-files","last_synced_at":"2026-01-21T12:00:29.949Z","repository":{"id":332620217,"uuid":"1134374030","full_name":"chenmudu/spec-workflow-files","owner":"chenmudu","description":" File-based spec workflow with hooks. Unlike Kiro (docs only), this creates \u0026 manages actual spec files. Pairs with planning-with-files for complete workflow: spec-workflow-files (planning) → planning-with-files (execution).","archived":false,"fork":false,"pushed_at":"2026-01-14T18:08:35.000Z","size":35,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-14T21:25:24.289Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chenmudu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-14T16:22:55.000Z","updated_at":"2026-01-14T18:08:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chenmudu/spec-workflow-files","commit_stats":null,"previous_names":["chenmudu/spec-workflow-files"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/chenmudu/spec-workflow-files","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenmudu%2Fspec-workflow-files","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenmudu%2Fspec-workflow-files/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenmudu%2Fspec-workflow-files/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenmudu%2Fspec-workflow-files/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chenmudu","download_url":"https://codeload.github.com/chenmudu/spec-workflow-files/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chenmudu%2Fspec-workflow-files/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28602175,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T10:46:13.255Z","status":"ssl_error","status_checked_at":"2026-01-20T10:42:51.865Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-18T09:18:40.521Z","updated_at":"2026-01-21T12:00:29.930Z","avatar_url":"https://github.com/chenmudu.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spec Workflow Files\n\nEnglish | [简体中文](README_CN.md)\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nFile-based spec workflow for systematic feature development. Creates structured documentation in `.specs/` directory with hooks for workflow enforcement.\n\n## 🎯 What is This?\n\nA Claude Code plugin that enforces a three-phase workflow for feature development:\n\n1. **Requirements** → Define WHAT to build (EARS format)\n2. **Design** → Define HOW to build it (architecture, APIs, data models)\n3. **Tasks** → Break down into actionable steps\n\n**Problem it solves:** AI coding often jumps straight to implementation without proper planning, leading to unclear requirements, poor architecture, and maintenance nightmares.\n\n**Solution:** Persistent files + hooks that guide you through proper planning phases.\n\n## 🚀 Quick Start\n\n### Requirements\n\n- **jq** - Required for workflow status checking and hooks\n  - Windows: Download from [jqlang.github.io/jq](https://jqlang.github.io/jq/download/)\n  - macOS: `brew install jq`\n  - Linux: `apt-get install jq` or `yum install jq`\n\n### Installation\n\n```bash\n# In Claude Code\n/plugin marketplace add chenmudu/spec-workflow-files\n/plugin install spec-workflow-files@spec-workflow-files\n```\n\n### Usage\n\n```bash\n# Initialize in your project\n/spec-workflow\n\n# This creates .specs/ directory with:\n# - requirements.md\n# - design.md\n# - tasks.md\n# - .workflow-confirmations.json\n```\n\n## 📁 File Structure\n\n```\nyour-project/\n├── .specs/                          # Spec files in dedicated directory\n│   ├── requirements.md              # Phase 1: What to build\n│   ├── design.md                    # Phase 2: How to build\n│   ├── tasks.md                     # Phase 3: Task breakdown\n│   └── .workflow-confirmations.json # Phase status tracking\n├── src/\n└── ...\n```\n\n## 🔄 Workflow\n\nThree phases with enforced sequencing:\n\n**Phase 1: Requirements** → Edit `.specs/requirements.md` with EARS format\n```markdown\nWHEN user submits valid login credentials THEN system SHALL authenticate user\n```\n\n**Phase 2: Design** → Edit `.specs/design.md` with architecture and APIs\n\n**Phase 3: Tasks** → Edit `.specs/tasks.md` with numbered implementation tasks\n\nMark each phase as confirmed before proceeding to the next.\n\n## 🎣 Hooks\n\nThe plugin uses hooks to guide your workflow:\n\n- **PreToolUse**: Warns if you skip phases (e.g., editing design before confirming requirements)\n- **PostToolUse**: Reminds you to confirm after editing\n- **Stop**: Shows workflow status before Claude stops\n\n## 🤝 Integration with Planning-with-Files (Optional)\n\nWorks standalone or combined with [planning-with-files](https://github.com/OthmanAdi/planning-with-files):\n\n- **Spec Workflow** → Planning (requirements → design → tasks in `.specs/`)\n- **Planning-with-Files** → Execution (task_plan.md, findings.md, progress.md in root)\n\nAfter completing all phases, the plugin suggests using planning-with-files if detected.\n\n## 📊 Feature Comparison\n\n| Feature | Spec Workflow Files | Planning-with-Files | Kiro |\n|---------|---------------------|---------------------|------|\n| **Purpose** | Planning \u0026 Documentation | Execution Tracking | Methodology Guide |\n| **Files** | 3 (in `.specs/`) | 3 (in root) | Documentation only |\n| **Hooks** | ✅ Yes | ✅ Yes | ❌ No |\n| **Phase Enforcement** | ✅ Yes | ❌ No | ❌ No |\n| **EARS Format** | ✅ Yes | ❌ No | ✅ Yes (guide) |\n| **Task Tracking** | ✅ Yes | ✅ Yes | ❌ No |\n| **Clean Directory** | ✅ `.specs/` | ⚠️ Root files | N/A |\n| **Best For** | Planning phase | Execution phase | Learning methodology |\n\n## 🎓 Best Practices\n\n1. **Complete each phase** - Don't skip ahead, each builds on the previous\n2. **Use EARS format** - `WHEN [trigger] THEN system SHALL [response]`\n3. **Document decisions** - Record why you chose an approach in design.md\n4. **Keep specs updated** - Update when requirements or design evolves\n5. **Combine with planning-with-files** - For complex projects needing execution tracking\n\n## 🎯 When to Use\n\n**✅ Use for:**\n- New feature development\n- Complex system changes\n- Projects requiring documentation\n- Team collaboration\n- AI-assisted development\n\n**❌ Skip for:**\n- Simple bug fixes\n- Trivial changes\n- Experimental prototypes\n- Time-critical hotfixes\n\n## 📖 Documentation\n\n- [Plugin Documentation](PLUGIN.md) - Installation and usage\n- [SKILL.md](skills/spec-workflow-files/SKILL.md) - Complete reference\n- [Templates](skills/spec-workflow-files/templates/) - Document templates\n\n## 📝 Example\n\nSee [PLUGIN.md](PLUGIN.md) for complete examples of requirements.md, design.md, and tasks.md.\n\n## 🤔 Philosophy\n\n**Core principles:**\n1. Files over memory - Persistent documentation beats volatile context\n2. Structure over chaos - Enforced phases prevent premature implementation\n3. Guidance over freedom - Hooks nudge toward best practices\n\n**Inspired by:** Manus (planning-with-files), Kiro (spec-driven development), EARS (requirements syntax)\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file\n\n## 👤 Author\n\n**chenmudu** - [@chenmudu](https://github.com/chenmudu)\n\n## 🙏 Acknowledgments\n\n- [OthmanAdi/planning-with-files](https://github.com/OthmanAdi/planning-with-files)\n- [jasonkneen/kiro](https://github.com/jasonkneen/kiro)\n- Meta's Manus\n\n---\n\n**Issues \u0026 Contributions:** https://github.com/chenmudu/spec-workflow-files/issues\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchenmudu%2Fspec-workflow-files","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchenmudu%2Fspec-workflow-files","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchenmudu%2Fspec-workflow-files/lists"}