work-planning · git:20260728.0e57a09 · 2026-07-28 · sha256 0796c9da51423a58
work-planning git:20260728.0e57a09A
Immutable. This exact content is served forever at /api/v1/blob/0796c9da51423a58.
---
name: work-planning
description: >
Design the complete work hierarchy for a Paperclip company — Goals, Projects,
and Tasks as a unified top-down planning workflow. Produces ._planning.json
for deterministic generation of goals/, projects/, and tasks/ directories.
Use when creating a new company's work plan, reorganizing work structure,
or linking goals to projects and tasks.
---
# Work Planning Skill
This skill designs the full work hierarchy for a Paperclip company following the Agent Companies specification (`agentcompanies/v1`). Work flows top-down: **Goal (Initiative) → Projects → Issues/Tasks → Sub-issues**.
Every piece of work in the company traces back to a goal. This skill produces a single `._planning.json` file consumed by `generate-plan.sh` to create all `goals/`, `projects/`, and `tasks/` directories deterministically.
## When to Use
- Creating a new company (called from `/company` Phases 2-3)
- Reorganizing or extending goals, projects, or tasks for an existing company
- Linking goals to projects and tasks
- User asks to "plan work", "define goals", "create projects", or "organize tasks"
## Step 1: Goal Design
Goals are the **strategic direction layer**. They define what success looks like.
### Goal Quality Bar
- **2-5 company goals** — fewer is better if they're precise
- Each goal must be **specific to this business** (not generic like "grow revenue")
- Goals must be **measurable or verifiable** (e.g., "Launch a public API with 3+ endpoints")
- Include a mix of product, growth, and operational goals
### Goal Fields
| Field | Required | Description |
|-------|----------|-------------|
| `slug` | Yes | Kebab-case, becomes folder name |
| `title` | Yes | The goal statement |
| `description` | Yes | Concrete deliverables or success criteria |
| `level` | No | `company`, `team`, `agent`, or `task` (auto-assigned by depth) |
| `status` | No | `planned`, `active`, `achieved`, `cancelled` (default: `active`) |
| `ownerAgentSlug` | Optional | Agent slug responsible for driving this goal (assigned after org design) |
| `projectSlugs` | Recommended | Projects that deliver on this goal |
### Building the Hierarchy
After confirming top-level goals, break each into subgoals:
1. **Subgoals** — 1-3 team-level workstreams per company goal. Every subgoal must include a `description`.
2. **Ownership** — can be deferred to an assignment step after org design. When assigning: company goals → C-level agents, subgoals → team leads or ICs.
3. **Project linkage** — connect each goal/subgoal to the projects that deliver on it.
4. **Depth** — 2 levels of nesting is usually enough. Max 4 levels.
**Checkpoint:** Present goals to the user and confirm before proceeding to Step 2.
## Step 2: Project Design
Projects group related work under a clear owner. Each project links to one or more goals.
### Project Scoping
| Scenario | Where it goes |
|----------|---------------|
| 3+ related tasks with shared theme and natural owner | **Project** — `projects/{slug}/` |
| One-off strategic directive from CEO | **Company-level task** — `tasks/` |
| Cross-cutting work spanning multiple domains | **Company-level task** — assigned to CEO |
| Ongoing operational work (reviews, reporting) | **Project task** with `recurring: true` — MUST be inside a project |
**Rule of thumb:** if 3+ tasks share a theme and a natural owner, they belong in a project.
### Project Fields
| Field | Required | Description |
|-------|----------|-------------|
| `slug` | Yes | Kebab-case, must match folder name |
| `name` | Yes | Human-readable project name |
| `description` | Yes | One-line summary of what the project delivers |
| `owner` | Optional | Agent slug of the project owner (assigned after org design) |
The project body should include `## Scope` and `## Success Criteria` sections.
### Scoping Guidelines
- 1-3 projects for a new company, more for larger orgs
- 3-8 tasks per project — fewer means too narrow, more means consider splitting
- Good names describe **outcomes** (`mvp-launch`, `api-v2`), not activities (`backend-work`)
- Every project slug must appear in at least one goal's `projectSlugs`
### Owner Selection
| Project Type | Typical Owner |
|-------------|---------------|
| Engineering / product build | CTO or lead engineer |
| Marketing campaign | CMO or content lead |
| Infrastructure / DevOps | CTO or DevOps engineer |
| Cross-functional initiative | CEO or PM |
## Step 3: Task Design
Tasks are the concrete work items. They live either under projects or at the company level.
### Task Ordering Convention
Tasks are imported in **alphabetical order by directory name**. IDs are assigned sequentially. To control import order, prefix task directory names with a two-digit number.
**Numbering must be globally unique across the entire company package.** Do not restart numbering per project — continue the sequence across all task locations:
```
projects/backend/tasks/
├── 01-setup-infrastructure/TASK.md
├── 02-build-auth/TASK.md
projects/frontend/tasks/
├── 03-design-ui/TASK.md
├── 04-build-components/TASK.md
tasks/
├── 05-strategic-review/TASK.md
├── 06-weekly-standup/TASK.md
```
Without numeric prefixes, tasks sort alphabetically by slug, which may not reflect intended execution order.
Note: `generate-plan.sh` assigns global ordering automatically — the `order` field in `._planning.json` is ignored. The script numbers tasks sequentially: all project tasks first (in project key order), then company-level tasks.
### Task Fields
| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Human-readable task name |
| `assignee` | Optional | Agent slug (assigned after org design, required before generation) |
| `project` | Yes (project tasks + all recurring tasks) | Parent project slug |
| `recurring` | No | `true` for ongoing work — task MUST be inside a project |
### Task Organization Rules
- Every project task lives at `projects/{project-slug}/tasks/{NN-task-slug}/TASK.md`
- Every project task has `project: {project-slug}` in frontmatter
- Company-level tasks live at `tasks/{NN-slug}/TASK.md` — one-off CEO strategic directives only
- **Recurring tasks MUST NEVER be company-level.** They must always live inside a project (`projects/{slug}/tasks/`). Recurring tasks become Routines, and Routines require a project. If no existing project fits, create a dedicated project (e.g. `operations`, `company-rituals`).
- Aim for **3-8 tasks per project**
- Task assignees can differ from the project owner
- Task slugs describe the deliverable (`setup-auth`, `build-landing-page`)
- All referenced `assignee` agent slugs must exist in `agents/`
## Step 4: Produce `._planning.json`
After the user confirms goals, projects, and tasks, write a `._planning.json` file in the company root with this structure:
```json
{
"goals": [
{
"slug": "launch-mvp",
"title": "Launch MVP web application",
"description": "Ship a functional product users can sign up for and use daily",
"level": "company",
"status": "active",
"ownerAgentSlug": "cto",
"projectSlugs": ["mvp-backend", "mvp-frontend"],
"subgoals": [
{
"slug": "build-auth-system",
"title": "Build authentication and user management",
"description": "Implement email/password and OAuth sign-up, session management, and RBAC",
"level": "team",
"ownerAgentSlug": "backend-engineer",
"projectSlugs": ["mvp-backend"]
}
]
}
],
"projects": [
{
"slug": "mvp-backend",
"name": "MVP Backend",
"description": "Backend API with auth, core workflow, and payment integration",
"owner": "backend-engineer",
"body": "## Scope\n\nBuild and deploy the backend API with:\n- User authentication (JWT)\n- Core business workflow endpoints\n- Stripe payment integration\n\n## Success Criteria\n\n- API deployed to production\n- All endpoints tested with 80%+ coverage"
}
],
"tasks": {
"projects": {
"mvp-backend": [
{
"slug": "setup-project",
"name": "Set up FastAPI project structure",
"assignee": "backend-engineer",
"body": "Initialize the FastAPI project with directory structure, dependencies, and Docker setup.",
"recurring": false
},
{
"slug": "build-auth",
"name": "Implement user authentication",
"assignee": "backend-engineer",
"body": "Implement JWT-based auth with email/password registration, login, and password reset.",
"recurring": false
},
{
"slug": "strategic-review",
"name": "Weekly strategic review",
"assignee": "ceo",
"body": "Review company progress against goals. Check blocked tasks, reassign if needed.",
"recurring": true
}
]
},
"companyLevel": []
}
}
```
Then run the generation script:
```bash
bash ${CLAUDE_PLUGIN_ROOT}/scripts/generate-plan.sh <company-root> <company-root>/._planning.json
```
This creates all `goals/`, `projects/`, and `tasks/` directories with proper frontmatter, ordering prefixes, and cross-references.
## Cross-Level Consistency Checks
Before producing `._planning.json`, verify:
- [ ] Every project slug appears in at least one goal's `projectSlugs`
- [ ] Every project task's `project` matches its parent project slug
- [ ] 2-5 top-level goals
- [ ] 3-8 tasks per project
- [ ] No duplicate slugs across goals, projects, or tasks
**Required before generation** (can be deferred during initial planning):
- [ ] Every goal's `ownerAgentSlug` exists in `agents/`
- [ ] Every task's `assignee` exists in `agents/`
- [ ] Every project's `owner` exists in `agents/`
## Common Planning Patterns
| Business Type | Goals | Projects | Task Examples |
|--------------|-------|----------|---------------|
| **SaaS MVP** | Launch product, acquire users, build pipeline | `mvp-launch`, `marketing-site`, `ci-cd-setup` | Auth, core features, landing page, CI pipeline |
| **E-commerce** | Launch store, scale inventory, payment flow | `storefront`, `inventory-system`, `payment-integration` | Product catalog, checkout, Stripe setup |
| **Content platform** | Launch CMS, grow audience, track metrics | `content-engine`, `distribution`, `analytics` | CMS setup, social posting, dashboard |
| **Agency** | Client portal, delivery pipeline, marketing | `client-portal`, `delivery-pipeline`, `marketing` | Project tracker, automation, outreach |