Product Introduction
Definition: Groundwork is an open-source, Apache-2.0 licensed developer skill designed for Claude Code, Codex, Gemini, Cursor, and 70+ other AI coding agents. Categorized as an AI agent planning and orchestration skill, it automatically scaffolds and maintains a living project plan folder consisting of structured markdown documents, execution trackers, and interactive HTML dashboards.
Core Value Proposition: Groundwork exists to solve the problem of "plan rot"—the common phenomenon where AI-generated project plans become outdated, inaccurate, or overwritten during iterative development cycles. By utilizing cryptographic SHA-256 checks on fenced code regions, Groundwork ensures that re-running automation tasks updates only the model-generated execution blocks while strictly preserving human-authored content, allowing developers to maintain a living, context-aware project folder across the entire software development lifecycle (SDLC).
Main Features
Checksum-Protected Safe Regeneration: Groundwork prevents data loss during repeated AI agent executions by wrapping generated sections in immutable fenced regions. When an action is re-run, a SHA-256 hash algorithm validates changes on disk, ensuring that human-written specifications, architectural notes, and custom adjustments outside the fenced blocks remain untouched and persistent.
Self-Contained Plan Board & Interactive Explorer: Groundwork automatically compiles tracker files into standalone HTML artifacts (
board.htmlandexplorer.html) requiring no external servers or network connectivity. The explorer provides a fully offline file tree, a tabbed document viewer, and full-text search across all markdown files, adapting its interface dynamically based on project profiles such asdesign-systemorfilm.Multi-Profile Scaffolding Engine: The skill supports five distinct workflows (
software,general,content,design-system, andfilm), adapting its vocabulary and structural blocks without altering its core execution engine. For instance, thesoftwareprofile manages work packages and pull requests, whereas thedesign-systemprofile introduces parts galleries, token pipelines, and quality gates.
Problems Solved
Pain Point: AI coding agents frequently hallucinate structural changes, overwrite manual documentation, and lose context over long-running engineering tasks, leading to fragmented project tracking, outdated requirements, and high maintenance overhead for developers.
Target Audience: Full-stack software engineers, AI-assisted development teams, technical product managers, open-source maintainers, and technical writers leveraging CLI coding agents like Claude Code, Cursor, and Gemini.
Use Cases: Groundwork is essential when scaffolding complex feature branches that require detailed architectural research, multi-phase engineering roadmaps, dependency mapping, and automated work-package tracking. It is also utilized for pre-production management in film and media pipelines via its dedicated
filmprofile.
Unique Advantages
Strengths & Limitations (Pros & Cons):
- Pros: Cryptographic protection against prompt overwrites; fully offline, zero-dependency HTML dashboards; support for over 70 AI agents via standard command-line tools; highly modular multi-profile architecture.
- Cons: Requires familiarity with CLI workflows and agentic coding environments; limited utility for trivial, single-file code changes where a structured plan folder introduces unnecessary overhead.
Key Alternatives & Differentiation:
- Linear / Jira: Traditional cloud-based project management tools; unlike Groundwork, they reside outside the codebase, lack cryptographic file-level preservation, and require manual synchronization with AI coding sessions.
- Standard Markdown READMEs: Static documentation that quickly rots; Groundwork differentiates itself through automated bi-directional syncing, live HTML plan boards, dependency graph visualization, and agent-driven review actions.
Frequently Asked Questions (FAQ)
Question: How do I install Groundwork for Claude Code?
- Answer: You can install Groundwork globally or per-project using the
npx skillspackage manager by runningnpx skills add ikenga-hq/groundwork -gfor global availability across all your projects, or via manual cloning into your~/.claude/skills/directory.
- Answer: You can install Groundwork globally or per-project using the
Question: Does Groundwork overwrite my personal notes inside the plan files?
- Answer: No. Groundwork uses fenced regions combined with SHA-256 checksum verification. Every time you re-run an action like
researchorreview, the model updates only its generated blocks, leaving all human-authored text intact.
- Answer: No. Groundwork uses fenced regions combined with SHA-256 checksum verification. Every time you re-run an action like
Question: Can I use Groundwork with AI agents other than Claude Code?
- Answer: Yes. Groundwork is compatible with Codex, Gemini, Cursor, and over 70 other coding agents that support agent skills and CLI workflows.
Question: What file structure does Groundwork create for a new project?
- Answer: Groundwork scaffolds a dedicated plan folder containing
.groundwork.jsonfor state tracking,00-README.md,01-plan.md, external and internal research files, discussion logs, tracking files for work packages, orchestration wave plans, and a standaloneboard.htmlartifact.
- Answer: Groundwork scaffolds a dedicated plan folder containing
