# Proj Work

> Open or run a work item under projects/{slug}/work/YYYY-MM-DD-{slug}/. Redirects brainstorming spec/plan output paths.

- Skill: `karlorz/proj-work` (Agent Skill)
- Install (CLI): `npx skillmds@latest add karlorz/proj-work`
- Raw SKILL.md: https://api.skillmd.com/api/skills/karlorz/proj-work/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: karlorz (https://skillmd.com/u/karlorz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/karlorz/proj-work

---


# proj-work

## Model routing

`proj-work` authors implementation specifications and plans, so its companion
agent must run at the invoking main-agent model. Keep `model: inherit` in the
plugin-root agent definition `agents/proj-work.md` (repository canonical source:
`packages/skills/agents/proj-work.md`; root `agents/proj-work.md` is a
materialized install mirror). Do not pin planning work to `sonnet`, `haiku`, or
`opus`. Do not add a `model` field to this `SKILL.md` frontmatter.

After plugin install the runtime path is
`<installed-plugin-root>/agents/proj-work.md` (for example
`~/.grok/installed-plugins/.../agents/proj-work.md`). Refresh a stale Grok
install with `grok plugin update skillwiki`, not `skillwiki install`.

## When to invoke
- User starts a feature, issue, refactor, or decision inside an existing project.
- User asks to "get work of X" or "run work item Y" to review/execute an existing item.
- Brainstorming would otherwise default-write outside the project tree.
- If no project context can be determined, default to the `playground` slug so redirect paths always emit and the PRD bridge chain works.

## Pre-orientation reads
Standard four + project context (project README, last ~5 work logs).

## Executing an Existing Work Item

When the user asks to "get work of X" or "run work item Y" for review, you are in EXECUTION mode — not creation mode. Steps:

1. **Resolve the work folder** at `<vault>/projects/{slug}/work/{YYYY-MM-DD-<slug>}/`. If the vault root isn't obvious, run `skillwiki path`.
2. **Read spec.md and tasks.md** in full. The spec defines scope; tasks define the review checklist.
3. **Verify every "DONE" claim against disk.** This is critical — previous sessions routinely mark items DONE in the wiki without actually applying the fix. For each claimed-complete task:
   - Check file existence, content, config values on disk
   - Cross-reference crontab entries, script timeouts, Makefile targets
   - Trust nothing in the wiki alone — validate
4. **Apply missing fixes**, then update the work item with accurate post-fix status.
5. **Set `status: complete`** when all fixes are verified.

## Creating a New Work Item
1. Determine `kind:` (feature | issue | refactor | decision) and slug.
2. Create folder `projects/{slug}/work/YYYY-MM-DD-{work-slug}/`.
3. Override default output paths for any nested skill: `spec.md`, `plan.md`, and `log.md` are written here, not at vault root.
4. Validate work-item frontmatter via `skillwiki validate <spec.md>`. If non-zero, STOP.
5. Manage status transitions: `planned` → `in-progress` → `completed` (set `completed:` date) or `abandoned`.
6. Append vault `log.md` entry on creation and on each status transition.

### Completion and post-release verification

- Work-item status represents delivery lifecycle. Mark delivery complete when
  the approved code, required acceptance checks, release/deployment scope, and
  completion evidence are finished.
- Required acceptance verification remains part of the completion checklist and
  must pass before `status: completed`.
- Optional verification after delivery uses typed frontmatter:
  `post_release_verification.posture: opt-in`, plus one or more approved
  `triggers` (`matching-regression-report`, `explicit-user-request`, or
  `relevant-code-or-release-change`).
- Record opt-in post-release checks as prose evidence, not as unchecked completion tasks.
  Completed opt-in work stays out of ordinary active rankings until a trigger
  occurs; a trigger creates new evidence or a follow-up decision rather than
  silently keeping delivered work `in-progress`.

## Redirect Output

After step 3 (output path override), emit redirect paths for the active PRD skill:

> Work item created: projects/{slug}/work/YYYY-MM-DD-{work-slug}/
>
> Redirect paths for PRD skills:
>   spec -> <vault-root>/projects/{slug}/work/YYYY-MM-DD-{work-slug}/spec.md
>   plan -> <vault-root>/projects/{slug}/work/YYYY-MM-DD-{work-slug}/plan.md
>
Rules:
- Emit redirect paths as the first output after folder creation, before any spec write.
- After the folder exists, brainstorming writes `spec.md` at the spec redirect.
- Do not invoke `writing-plans`. Do not git commit from brainstorming.
- `plan.md` is a later explicit `proj-work` step, not a Superpowers plan file.
- Resolve `<vault-root>` via `skillwiki path` (never hardcode).
- proj-work does NOT invoke brainstorming — it provides paths only.
- If a foreign PRD skill cannot accept custom save paths, fall back to manual `wiki-ingest`.
- When `spec.md` or `plan.md` mentions repo files, follow `using-skillwiki` → Portable Source References.

## Pitfalls
- **Wiki-as-truth fallacy**: tasks.md status markers are aspirational claims by previous sessions. They are often wrong. Always audit the actual file system before accepting a "DONE" label.
- **Re-marking without doing**: do not simply re-write tasks.md to say DONE without applying the corresponding fix. The next session will find the same gap.

## Stop conditions
- `validate` non-zero.
- Conflicting work folder name.

## Forbidden
- Writing spec/plan files outside the work folder.
- Marking `status: completed` without a `completed:` date.
- Accepting tasks.md status labels without independent disk verification.
## Managed writes

Use managed SkillWiki commands (`skillwiki page publish`, `skillwiki archive`) rather than editing root index.md/log.md directly.