Agent Skills: Setup Matt Pocock Skills

Setup Matt Pocock Skills

Configure the shared substrate used by the engineering skills:

• Alignment storage — repository-local or shared outside the repository
• Issue tracker — GitHub, GitLab, local Markdown, or another workflow, independent of alignment storage
• Triage labels — actual tracker strings for the canonical workflow roles
• Domain docs — where CONTEXT.md, CONTEXT-MAP.md, and ADRs live

Read ALIGNMENT-ROOT.md before starting.

Process

1. Discover current state

Inspect the system prompt for <matt-pocock-context>. Record its storage, root, shared-root, repository-root, source, origin, and slug attributes.

Inspect the repository root for:

• AGENTS.md and CLAUDE.md, including any existing ## Agent skills section
• CONTEXT.md, CONTEXT-MAP.md, docs/adr/, and src/*/docs/adr/
• docs/agents/
• .scratch/
• git remote -v

If shared-root is available, inspect that directory for the same alignment files. Missing shared directories are normal before first setup.

2. Ask for configuration

Present the findings, explain each choice briefly, then collect these decisions together with the structured ask tool.

Alignment storage:

• Repository — engineering configuration and domain documentation live in the repository.
• Shared context — engineering configuration and domain documentation live beneath the injected shared-root, outside the repository. Requires the Matt Pocock context extension.

This choice controls only where engineering configuration is stored. It MUST NOT constrain the issue tracker backend.

Default to the currently active storage. If no <matt-pocock-context> exists, repository storage is the only valid choice; do not invent a shared path.

Issue tracker:

• GitHub — use gh; propose when origin points at GitHub
• GitLab — use glab; propose when origin points at GitLab
• Local Markdown — issues live beneath .scratch/ in the selected alignment root
• Other — Jira, Linear, or another user-described workflow

Every tracker backend is valid with either alignment-storage mode. Storage controls the location of docs/agents/issue-tracker.md; its backend metadata controls how issues are tracked.

For GitHub or GitLab, also ask whether external pull requests are a triage request surface. Default: no.

Triage labels:

Ask whether any canonical role maps to a different tracker string: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix. Default each role to its own name.

Domain layout:

• Single-context — CONTEXT.md and docs/adr/ beneath the alignment root
• Multi-context — CONTEXT-MAP.md beneath the alignment root points to context glossaries and ADR directories beneath that same root

Default to the layout already present; otherwise single-context.

3. Resolve output root

• Repository storage: ALIGNMENT_ROOT is repository-root from the injected context, or the Git repository root when no context was injected.
• Shared storage: ALIGNMENT_ROOT is shared-root from the injected context. It MUST be an absolute path beneath ~/.pi/shared-context/.

All output paths below are relative to ALIGNMENT_ROOT.

4. Draft and confirm

Show one draft containing:

• Target alignment root and storage mode
• ## Agent skills block
• docs/agents/issue-tracker.md
• docs/agents/triage-labels.md
• docs/agents/domain.md

Let the user edit the draft before writing.

The block:

## Agent skills

### Issue tracker

[summary]. See `docs/agents/issue-tracker.md` relative to the active Matt Pocock alignment root.

### Triage labels

[summary]. See `docs/agents/triage-labels.md` relative to the active Matt Pocock alignment root.

### Domain docs

["single-context" or "multi-context" summary]. See `docs/agents/domain.md` relative to the active Matt Pocock alignment root.

5. Write

Create files lazily and preserve unrelated user content.

For repository storage:

1. If CLAUDE.md exists, update it.
2. Else if AGENTS.md exists, update it.
3. If neither exists, ask which one to create.
4. Never create the other file when one already exists.

For shared storage:

1. Create ALIGNMENT_ROOT if needed.
2. Update or create ALIGNMENT_ROOT/AGENTS.md.
3. MUST NOT edit repository AGENTS.md or CLAUDE.md.

If ## Agent skills already exists, update it in place rather than adding a duplicate.

Every generated docs/agents/issue-tracker.md MUST begin with YAML frontmatter naming the actual backend, such as backend: github, backend: gitlab, backend: jira, or backend: local-markdown. Local Markdown MUST also declare issue-root: .scratch. Migration uses this metadata and MUST NOT infer the backend from prose.

Write the three configuration files using these seeds:

• issue-tracker-github.md
• issue-tracker-gitlab.md
• issue-tracker-local.md for local Markdown in either storage mode
• triage-labels.md
• domain.md

For another tracker, write docs/agents/issue-tracker.md from the user's description and set backend to the actual service identifier, such as jira or linear.

Configuration and domain documents created by this workflow MUST stay beneath the selected alignment root. Only the Local Markdown backend stores issue data there, beneath .scratch/; external tracker data remains in its external service. Source code remains in the repository.

6. Finish

Report the absolute alignment root and files written. First-time shared setup activates on the next agent turn because the extension resolves the file for every turn.