PawlKit

A portable, repo-local project operating kit for AI coding agents.

What it is

PawlKit is a small set of files you copy into a software repository so AI coding agents (Claude Code, Codex, OpenCode, and other AGENTS.md-aware tools) have stable, durable context about the project. It standardizes where the current sprint, current task, decisions, scope, commands, and evidence for completed work live, so agents stop drifting between sessions.

PawlKit is not an app. It is not hosted. It has no database. It has no dashboard. It is a documentation scaffold plus a tiny zero-dependency installer.

Why

Coding agents are powerful but forgetful. They lose direction across sessions, re-derive decisions, work on future-sprint features early, quietly drift out of scope, and sometimes make failures disappear by bypassing tests or narrowing behavior instead of fixing the bug. PawlKit gives them a fixed place to look — .pawl/active/CURRENT.md — and a fixed set of rules to follow.

PawlKit also keeps planning files small on purpose. Index files hold pointers and status tables; full project, sprint, task, and decision details live in separate records that can be archived after their TTL.

Quick install

cd /path/to/target-repo
npx @codepawl/pawlkit

Runs in the current directory. Existing files are preserved (skipped). After the copy you'll get a Run setup wizard now? [Y/n] prompt — hit Enter to fill .pawl/context/*.md from your project's metadata. Requires Node ≥ 18. See Install for tiged, curl/tar, and local-clone alternatives.

Tracking main between releases? npx github:codepawl/pawlkit still works and pulls the tip of the repo.

What it installs

When you run the installer (or copy the template manually), the target repo gets:

.pawl/
  README.md
  active/
    CURRENT.md      # the active dashboard (start here)
    SPRINTS.md      # short compatibility index
    TASKS.md        # short compatibility index
    DECISIONS.md    # short compatibility index
    projects/
      INDEX.md
      project-main.md
    sprints/
      INDEX.md
      sprint-000-pawlkit-setup.md
    tasks/
      INDEX.md
      t000-setup-pawlkit.md
    decisions/
      INDEX.md
      d001-use-pawl-folder.md
      d002-small-sprints.md
      d003-active-over-archive.md
  context/
    PRODUCT_SCOPE.md
    TECHNICAL_SCOPE.md
    DOMAIN_NOTES.md
    REPO_COMMANDS.md
  templates/
    project.md
    sprint.md
    task.md
    decision.md
  archive/
    README.md
    projects/
      README.md
    sprints/
      README.md
    tasks/
      README.md
    decisions/
      README.md
  logs/
    changelog.md

.agents/
  instructions.md   # generic fallback for any AGENTS.md-aware tool
  workflow.md

.claude/
  commands/
    plan-sprint.md  # /plan-sprint
    start-task.md   # /start-task
    finish-task.md  # /finish-task
    review-scope.md # /review-scope
    init-pawl.md    # /init-pawl
  skills/
    pawl-init/
      SKILL.md

.codex/
  skills/
    pawl-init/
      SKILL.md

AGENTS.md           # the cross-agent entry point

Supported agents

• Claude Code — reads AGENTS.md, exposes .claude/commands/* as slash commands (/plan-sprint, /start-task, /finish-task, /review-scope, /init-pawl), and loads .claude/skills/pawl-init/SKILL.md as a skill.
• Codex — reads AGENTS.md and loads .codex/skills/pawl-init/SKILL.md.
• OpenCode / other generic agents — read AGENTS.md plus .agents/instructions.md and .agents/workflow.md.

All three paths point at the same .pawl/ folder, so the project's source of truth stays consistent regardless of which agent is driving.

Install

Four ways, in order of friction. Most people should use (A).

Works on Windows 10/11, macOS, Linux, and WSL. Methods A, B, and D need Node ≥ 18. Method C needs only curl and tar — both ship with Windows 10 1803+, macOS, and every modern Linux distro.

A. npx @codepawl/pawlkit — recommended

One command from inside the target repo. Pulls the published package from npm.

cd /path/to/target-repo
npx @codepawl/pawlkit

What it does: npx fetches PawlKit into its temporary cache, runs scripts/init-pawlkit.mjs, and the script copies templates/default/ into the current directory. Existing files are skipped.

• Pin to a release for reproducibility: npx @codepawl/[email protected]
• Overwrite existing files: npx @codepawl/pawlkit --force
• Skip the wizard prompt: npx @codepawl/pawlkit --no-setup
• Run wizard immediately, no prompt: npx @codepawl/pawlkit --setup
• Install from GitHub instead (tip of main, unreleased commits): swap @codepawl/pawlkit for github:codepawl/pawlkit in any of the above

Maintenance commands

After PawlKit is installed in a target repo, the same CLI can maintain the .pawl/ structure:

npx @codepawl/pawlkit check
npx @codepawl/pawlkit view
npx @codepawl/pawlkit view --type task
npx @codepawl/pawlkit view --all --status Done
npx @codepawl/pawlkit integrate --dry-run
npx @codepawl/pawlkit integrate
npx @codepawl/pawlkit merge --dry-run
npx @codepawl/pawlkit merge
npx @codepawl/pawlkit archive --dry-run
npx @codepawl/pawlkit archive
npx @codepawl/pawlkit new task "Fix login timeout"
npx @codepawl/pawlkit new sprint "Stabilize auth"
npx @codepawl/pawlkit new decision "Use SQLite for local state"
npx @codepawl/pawlkit new project "Mobile app"

• check validates required files, record metadata, index sizes, archive folders, and broken .pawl links.
• view prints a read-only terminal dashboard of current pointers, record counts, statuses, file paths, and TTL/archive labels.
• integrate creates or repairs Claude Code, Codex, generic agent files, and AGENTS.md so coding agents know to use .pawl/.
• merge upgrades an existing PawlKit .pawl/ folder to the current split-file structure while preserving legacy tracker content in archive.
• archive --dry-run reports TTL warnings, missing archive dates, and expired records without changing files.
• archive only moves records with terminal statuses (Done, Completed, Cancelled, Superseded, Rejected, or Abandoned); when a terminal record has Completed but no archive dates, it fills the default 30-day TTL and 7-day warning first.
• new creates a record from the matching template and updates the relevant short index. It refuses to overwrite existing files.

Setup wizard

After the template is copied, PawlKit offers a 5-question wizard that fills in .pawl/context/*.md from your project's own metadata (package.json, Cargo.toml, pyproject.toml, go.mod, or lockfiles). Most fields are auto-detected — press Enter to accept each default.

Fields:

| # | Field | Writes into | |---|---|---| | 1 | Project name | active/CURRENT.md, context/PRODUCT_SCOPE.md | | 2 | One-line description | context/PRODUCT_SCOPE.md | | 3 | Primary stack | context/TECHNICAL_SCOPE.md | | 4 | Install command | context/REPO_COMMANDS.md, context/TECHNICAL_SCOPE.md | | 5 | Test command | context/REPO_COMMANDS.md, context/TECHNICAL_SCOPE.md |

Re-run later at any time with npx @codepawl/pawlkit --setup. The wizard is idempotent — it reads each section's current value and offers it as the new default, so you can revise any answer without re-typing the rest.

The wizard never touches a field once you've edited it by hand. Everything it skips (sprint goals, success criteria, domain notes, etc.) stays as TODO: markers — fill those in directly or use /init-pawl in Claude Code to have an agent draft them.

B. npx tiged — fetches only the template subdir

Skips the PawlKit wrapper and pulls only the installable payload.

cd /path/to/target-repo
npx tiged codepawl/pawlkit/templates/default .

• The target directory must be empty by default. To install into a non-empty repo, add --force: npx tiged codepawl/pawlkit/templates/default . --force.
• Tiged is the maintained fork of degit.

C. curl + tar — no Node required

Pure shell. Useful in CI images or restricted environments that don't ship Node.

macOS / Linux / WSL / Windows cmd:

cd /path/to/target-repo
curl -L https://github.com/codepawl/pawlkit/archive/refs/heads/main.tar.gz \
  | tar -xz --strip-components=3 pawlkit-main/templates/default

Windows PowerShell — PowerShell aliases curl to Invoke-WebRequest, so call curl.exe explicitly and use a two-step download/extract:

cd C:\path\to\target-repo
curl.exe -L https://github.com/codepawl/pawlkit/archive/refs/heads/main.tar.gz -o pawlkit.tar.gz
tar -xz --strip-components=3 pawlkit-main/templates/default -f pawlkit.tar.gz
Remove-Item pawlkit.tar.gz

• --strip-components=3 drops the pawlkit-main/templates/default/ prefix so files land at the repo root.
• This overwrites existing files at those paths without prompting — use with care.
• Pin to a release: replace heads/main with tags/v0.3.0 and pawlkit-main with pawlkit-0.3.0.

D. Local clone — fallback

If you want the full PawlKit source on disk (e.g. to read the templates before installing):

git clone https://github.com/codepawl/pawlkit.git
cd /path/to/target-repo
node /path/to/pawlkit/scripts/init-pawlkit.mjs

The installer:

• copies every file from templates/default/ into the current working directory
• skips files that already exist (your content is preserved)
• prints a create: / skip: line per file and a final summary
• pass --force to overwrite existing files

How .pawl/ works

Six rules. That's the whole thing.

1. Read .pawl/active/CURRENT.md first. It points at the current sprint, current task, and everything else the agent needs.
2. Active overrides archive. Files under .pawl/active/ are the source of truth. Files under .pawl/archive/ are historical context only.
3. Update the trackers after meaningful work. When a task moves, a decision is made, or a sprint advances, write it back. A stale .pawl/ is worse than no .pawl/.
4. Finish with evidence. For bug fixes and implementation tasks, agents record current behavior, expected behavior, root cause, fix strategy, verification, and regression coverage before marking work done.
5. Keep files short. Indexes contain pointers and status tables; full details live in one record file per project, sprint, task, or decision.
6. Apply TTL. Completed, cancelled, superseded, or rejected records default to 30 days active retention, with a warning 7 days before archive.

After installing, fill in the TODO: markers in .pawl/context/PRODUCT_SCOPE.md, .pawl/context/TECHNICAL_SCOPE.md, and .pawl/context/REPO_COMMANDS.md so the agents have something real to read. Then define Sprint 1 as a new file under .pawl/active/sprints/ and link it from .pawl/active/sprints/INDEX.md.

Small-file structure

PawlKit uses short indexes plus detailed records:

• .pawl/active/CURRENT.md points to the current project, sprint, and task.
• .pawl/active/{projects,sprints,tasks,decisions}/INDEX.md files stay short and list active records.
• Each project, sprint, task, and decision gets its own Markdown file.
• The top-level SPRINTS.md, TASKS.md, and DECISIONS.md files are compatibility indexes only; do not append full records there.

Agent integration and merge

Use pawlkit integrate when a repository already has source code or existing agent files and you want Claude Code, Codex, OpenCode, or other AGENTS-aware tools to pick up PawlKit. Existing agent files that already mention .pawl/ are preserved; existing files that do not mention PawlKit get a small marked integration block appended instead of being overwritten.

Use pawlkit merge when a repository already has an older PawlKit .pawl/ folder. It creates missing split-file indexes, templates, and archive folders. If legacy monolithic SPRINTS.md, TASKS.md, or DECISIONS.md files contain detailed bodies, PawlKit preserves those bodies under .pawl/archive/*/legacy-*.md and replaces the active tracker with a short compatibility index.

TTL archiving

Project, sprint, task, and decision records include TTL fields. By default, completed, cancelled, superseded, or rejected records stay active for 30 days. Agents add a warning note 7 days before Archive After, then move expired records to the matching .pawl/archive/{projects,sprints,tasks,decisions}/ folder and leave a short pointer in the active index.

Anti-bypass constraints

PawlKit's default task and agent instructions make bug fixes evidence-gated. Agents are told to fix root causes instead of masking symptoms, and they must not remove, skip, weaken, or fake tests/checks to make work pass. They also must not hard-code around failing cases, delete behavior, narrow scope, add broad mocks, or disable validation/error handling unless the active task explicitly requires that approach.

If the correct fix requires a scope or architecture change, the agent should record the decision instead of silently routing around the issue.

Privacy & security

PawlKit is a file copier. It is intentionally inert:

• No network calls. The installer reads templates/default/ from its own package and writes to your cwd. Nothing else.
• No telemetry. No analytics, no pings — there is nothing to opt out of.
• No shell execution. The installer never runs commands on your behalf. The wizard reads package.json, Cargo.toml, pyproject.toml, and go.mod as text to suggest defaults; it does not execute them or any script they reference.
• Writes are scoped to the target directory. The installer refuses to write any file whose resolved path falls outside cwd, and skips symlink entries in the template rather than following them.
• Existing files are preserved. Without --force, the installer skips every file that already exists. With --force, it overwrites — but only inside cwd.
• Wizard inputs are line-bounded. Each section in .pawl/context/*.md is a single line; the wizard strips CR/LF from answers and detected values before writing so a multi-line paste can't corrupt the file structure.
• Zero runtime dependencies. package.json lists none. The bin is two .mjs files using only the Node standard library.

For reproducibility, pin to a published version (npx @codepawl/[email protected]) and verify the tarball with npm view @codepawl/[email protected] dist.