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
  policy.yaml       # structured workspace policy source of truth
  version           # workspace schema version marker
  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 And Validation Commands

Use install commands when adding PawlKit to a repo. Use validation commands after PawlKit is already present.

Common wrong command: npx pawlkit. The npm package is scoped, so use @codepawl/pawlkit.

Do not copy /tmp/pawlkit-... or other temporary npx cache paths into durable repo docs. Those paths are only useful while debugging one local npx run and are not stable validation commands.

For repeatable tracker validation, pin a published version: @codepawl/pawlkit@<pinned-version>. Use unpinned npx @codepawl/pawlkit only when you intentionally want the latest published package. CI and durable repo docs should pin a version, and after upgrading PawlKit, update the pinned version intentionally.

npx may need npm registry and DNS access when the requested package is not already cached. For offline or restricted environments, install PawlKit as a dev dependency or ensure the pinned package is cached before validation. Do not make validation depend on temporary /tmp npx paths.

PawlKit colorizes CLI output when stdout is an interactive terminal. Set NO_COLOR=1 to disable color. Status symbols and status text remain present so output is still readable without color.

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

Install examples:

npx @codepawl/pawlkit
npx @codepawl/pawlkit@<version>
npx @codepawl/pawlkit@<version> --no-setup
npx @codepawl/[email protected]
npx @codepawl/[email protected] --no-setup

Universal Validation

Use pinned universal validation commands in CI and durable repo docs. These work for both policy-first workspaces and legacy workspaces:

npx @codepawl/pawlkit@<pinned-version> doctor
npx @codepawl/pawlkit@<pinned-version> check
npx @codepawl/pawlkit@<pinned-version> view
npx @codepawl/[email protected] doctor
npx @codepawl/[email protected] check
npx @codepawl/[email protected] view

Policy-First Validation

Use policy validation only after .pawl/policy.yaml exists:

npx @codepawl/pawlkit@<pinned-version> policy validate
npx @codepawl/[email protected] policy validate

Legacy workspaces can pass doctor, check, and view while policy validate fails because .pawl/policy.yaml is missing. That is expected until migration creates the policy file.

Legacy Migration

For a legacy workspace, preview migration first, then migrate, then validate policy:

npx @codepawl/pawlkit@<pinned-version> migrate --dry-run
npx @codepawl/pawlkit@<pinned-version> migrate
npx @codepawl/pawlkit@<pinned-version> policy validate
npx @codepawl/[email protected] migrate --dry-run
npx @codepawl/[email protected] migrate
npx @codepawl/[email protected] policy validate

You can also ask the installed CLI to print the current recommended command set:

pawlkit commands

Maintenance commands

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

npx @codepawl/[email protected] commands
npx @codepawl/pawlkit check
npx @codepawl/pawlkit view
npx @codepawl/pawlkit view --type task
npx @codepawl/pawlkit view --all --status Done
npx @codepawl/pawlkit doctor
npx @codepawl/pawlkit migrate --dry-run
npx @codepawl/pawlkit migrate
npx @codepawl/pawlkit report --format markdown
npx @codepawl/pawlkit report --format json
npx @codepawl/pawlkit policy validate
npx @codepawl/pawlkit policy render --format markdown
npx @codepawl/pawlkit policy render --format prompt
npx @codepawl/pawlkit release preflight
npx @codepawl/pawlkit release preflight --check-npm
npx @codepawl/pawlkit mcp
npx @codepawl/pawlkit trace validate
npx @codepawl/pawlkit trace timeline
npx @codepawl/pawlkit trace graph --format json
npx @codepawl/pawlkit trace graph --format json --output .pawl/logs/traces/graph.json
npx @codepawl/pawlkit project status
npx @codepawl/pawlkit task list
npx @codepawl/pawlkit task read t000
npx @codepawl/pawlkit task lock t000 --agent codex
npx @codepawl/pawlkit task note t000 --message "Current finding"
npx @codepawl/pawlkit task evidence t000 --tests passed --build not_run --changed-file README.md
npx @codepawl/pawlkit task transition t000 --to review
npx @codepawl/pawlkit task unlock t000 --agent codex
npx @codepawl/pawlkit handoff create --task t000
npx @codepawl/pawlkit task lock t000 --agent codex --observe-policy --mode review_only
npx @codepawl/pawlkit --observe-policy --mode review_only task read t000
npx @codepawl/pawlkit task note t000 --message "Review note" --enforce-policy --mode review_only
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.
• doctor checks whether .pawl/, .pawl/version, .pawl/policy.yaml, and legacy agent instruction files are present, then reports ok, warning, or error lines.
• migrate --dry-run previews the policy/version files and migration report PawlKit would create without changing files.
• migrate creates missing .pawl/, .pawl/policy.yaml, .pawl/version, and .pawl/migration-report.md files without deleting or rewriting AGENTS.md or .agents/*.
• report --format markdown prints a compact read-only workspace report with current pointers, record counts, task status, policy, trace, release-readiness, and recommended next commands.
• report --format json prints the same report as stable uncolored JSON with schema_version: 1. It does not mutate .pawl/, append trace events, run network npm checks, publish, tag, push, or change versions.
• policy validate validates .pawl/policy.yaml and exits non-zero when the policy file is missing or invalid. On legacy workspaces, run migrate --dry-run before treating this as a required validation command.
• policy render prints a concise generated Markdown or prompt summary while keeping .pawl/policy.yaml as the source of truth.
• release preflight runs local release readiness checks without publishing, tagging, pushing, committing, or changing package versions. It checks git cleanliness, branch/upstream status, package/changelog/version consistency, local tag absence, workspace doctor, and policy validation. Build/typecheck/test scripts are reported as recommended commands instead of run automatically.
• release preflight --check-npm opts into a network-aware npm registry check for the exact package.json name and version. Existing published versions are errors. Not-found responses are ok. Ambiguous npm, auth, registry, or network failures are warnings by default. Without --check-npm, the npm registry check is skipped and no network call is made.
• mcp runs a read-only PawlKit MCP stdio server for agents. MCP v0 exposes project status, tasks, decisions, policy status, trace summary, report export, and command guidance tools only.
• trace validate reads .pawl/logs/traces/latest.jsonl or --trace <path>, counts valid events, malformed lines, missing timestamps, and unknown event types, and only fails for missing traces or traces with no valid events.
• trace timeline prints a readable timeline from existing trace JSONL without mutating project state. Unknown event types and malformed lines are warnings when at least one valid event exists.
• trace graph --format json exports a lightweight graph with schema_version, nodes, and edges from existing trace events. It writes to stdout by default and only writes a file when --output <path> is provided.
• project status summarizes task counts and active locks.
• task list and task read inspect active task records without changing them.
• task lock and task unlock coordinate ownership with locked_by, locked_at, and lock_reason task state.
• task note appends a note to a task.
• task evidence updates structured evidence fields (tests, build, acceptance_checked, handoff, and changed_files) without rewriting human-authored task content.
• task transition moves a task through backlog, ready, in_progress, blocked, review, done, or cancelled. Transitioning to done requires completion evidence such as a handoff artifact.
• handoff create writes a handoff artifact and records it as task evidence.
• --observe-policy runs audit-only policy checks for supported PawlKit CLI actions and emits policy trace events. It reports would_block results but does not enforce or block yet. It may appear before or after the subcommand.
• --enforce-policy blocks the small supported policy violation set and emits policy_blocked. It currently covers review-only task writes, lock/unlock conflicts, and done transitions without evidence. It is not a shell, git, release, or filesystem enforcement hook.
• --mode <mode> selects the observe-only policy mode. If omitted with --observe-policy, PawlKit uses implementation and reports that default. It may appear before or after the subcommand.
• 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.5 and pawlkit-main with pawlkit-0.3.5.

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 package binary is bin/pawlkit.mjs; scripts/init-pawlkit.mjs remains as a compatibility shim for older local-clone instructions.

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.

Repository layout

Runtime code now lives in TypeScript under src/, with compiled JavaScript in dist/ and compatibility wrappers left in bin/ and scripts/:

• bin/pawlkit.mjs is the package binary entrypoint.
• src/cli/index.ts contains CLI dispatch and installer runtime.
• src/cli/setup-wizard.ts contains setup wizard runtime.
• src/core/pawlkit-ops.ts contains the current workspace/task/policy/release operations module.
• src/policy/, src/tasks/, src/handoff/, src/trace/, and src/migrate/ contain the staged TypeScript foundation for those domains.
• dist/ is generated by bun run build.

bin/pawlkit.mjs, scripts/init-pawlkit.mjs, scripts/pawlkit-ops.mjs, and scripts/setup-wizard.mjs are thin .mjs compatibility wrappers around compiled dist/ output. Published npm packages include the compiled runtime, templates, docs, and compatibility wrappers; TypeScript source and tests stay in the repository. The large runtime ports currently use staged TypeScript checking while behavior is preserved; tighter runtime typing can be added incrementally without changing workspace formats.

CI and release

Bun is the primary package manager for PawlKit development and CI:

bun install --frozen-lockfile
bun run build
bun run typecheck
bun run prepublishOnly
bun run check:package

GitHub Actions runs CI on pull requests and pushes to main, plus release checks for v* tags and manual dispatch. The npm registry remains the publish target, and npm/npx compatibility remains supported for users. The manual publish workflow is Bun-first for install/build/test and uses npm Trusted Publishing/OIDC for the registry publish step, so the preferred workflow does not require an NPM_TOKEN secret. pnpm is no longer part of the release flow. See CI and release docs for the local prep flow, tag/version safety rules, package artifact verification, and Bun-first npm publishing notes.

Workspace policy

PawlKit workspaces include .pawl/policy.yaml and .pawl/version. The current default policy is intentionally small:

schema_version: 1
policy_version: 1
agents: {}
modes: {review_only: Review-only audit, implementation: Implementation work}
capabilities: {review_only: read_project read_policy release_preflight, implementation: read_project read_policy write_task write_handoff release_preflight}
protected_paths: []
state_transitions: {}
release_rules: {}

Use pawlkit doctor to inspect a workspace before changing it. Older workspaces without .pawl/policy.yaml continue to work, but PawlKit will recommend pawlkit migrate --dry-run so you can preview the non-destructive policy/version migration first.

PawlKit currently parses .pawl/policy.yaml as a small YAML subset, not arbitrary YAML. Supported policy values are top-level key: value lines with simple values: {}, [], integers, quoted strings, unquoted strings, simple lists like [a, b], and one-level inline mappings like {review_only: read_project read_policy, implementation: read_project read_policy write_task write_handoff}. Nested mappings, nested lists, and indented YAML blocks are not supported yet; validation fails instead of accepting them. After editing policy, run:

pawlkit policy validate

Project state and trace events

PawlKit task commands extend existing task Markdown files with a generated PawlKit Task State section only when a write command needs it. Notes are appended under PawlKit Notes. Trace events are append-only JSONL at .pawl/logs/traces/latest.jsonl.

Task lock and unlock commands are idempotent for the same agent and emit conflict trace events instead of overwriting another agent's lock. task evidence updates structured evidence one field at a time and can append changed files with repeated --changed-file flags. handoff create writes a Markdown handoff, records the latest handoff path in task evidence, and states when tests/build evidence is missing instead of claiming success. Task transitions validate the target status, emit rejected transition traces for invalid transitions, and check completion evidence before allowing done. Minimal completion evidence is one of: a handoff path, explicit tests: passed|failed, or explicit build: passed|failed.

release preflight emits release_preflight_started, one release_preflight_check event per check, and either release_preflight_passed or release_preflight_failed. It also emits policy trace events for the release preflight action.

Trace analysis commands are read-only unless trace graph --output <path> is explicitly used. The graph JSON uses schema version 1 and includes stable node IDs for event-derived task, agent, policy_rule, action, release_check, handoff, file, and event nodes. Edge types include performed, checked, allowed, blocked, transitioned, updated, created, and referenced.

Milestones 2A-2E add state tools, trace events, structured evidence, handoffs, and observe-first policy checks only. They do not add runtime policy enforcement, graph analysis, or release hooks.

MCP integration

PawlKit includes an MCP v0 stdio server for the CodePawl ecosystem:

pawlkit mcp

The v0 server is read-only and exposes no shell execution, Notion writes, Obsidian writes, CloudPawl upload, or workspace format changes. See the MCP docs:

• Architecture
• Security
• Agent communication
• Notion sync contract
• Obsidian sync contract

Policy checks

PawlKit can audit supported CLI actions before running them:

pawlkit task lock t000 --agent codex --observe-policy --mode review_only
pawlkit --observe-policy --mode review_only task read t000

Observe-only checks are policy-driven from .pawl/policy.yaml. modes names each mode, and capabilities maps each mode to a space-separated capability list.

Current action classes:

• read_project: project status, task list, task read, and doctor
• read_policy: policy validate and policy render
• release_preflight: release preflight
• write_task: task lock, task unlock, task note, and task transition
• write_handoff: handoff create

Default observe-only modes:

• review_only allows read_project, read_policy, and release_preflight; missing write capabilities produce would_block results.
• implementation allows read_project, read_policy, write_task, write_handoff, and release_preflight.

Observe-only mode never blocks the command. It emits policy_checked plus policy_allowed or policy_would_block trace events before the command action event. Those events include the action capability that was checked.

Minimal enforcement is available for already-modeled invalid workflow actions:

pawlkit task note t000 --message "Review note" --enforce-policy --mode review_only

--enforce-policy emits policy_checked plus policy_blocked and exits non-zero for review-only task writes, lock/unlock conflicts, done transitions without evidence, and failed release preflight checks. It does not publish releases, inspect arbitrary shell commands, or enforce git operations outside PawlKit commands. --observe-policy and --enforce-policy cannot be combined.

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.