mirror of
https://github.com/SikongJueluo/pi-extensions.git
synced 2026-10-05 11:52:55 +08:00
docs: add agent guidance and permission research docs
- add AGENTS.md and docs for issue tracker, triage labels, and domain docs - add CONTEXT.md glossary for the permission authorization domain - add research report on context ownership for forwarded bash asks - ignore .pi-subagents and .codegraph directories - remove pi-permission-ai-judge from settings packages
This commit is contained in:
@@ -0,0 +1,37 @@
|
||||
# Domain Docs
|
||||
|
||||
How the engineering skills should consume this repo's domain documentation when exploring the codebase.
|
||||
|
||||
## Before exploring, read these
|
||||
|
||||
- **`CONTEXT.md`** at the repo root.
|
||||
- **`docs/adr/`** — read ADRs that touch the area you're about to work in.
|
||||
|
||||
If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
|
||||
|
||||
## File structure
|
||||
|
||||
Single-context repo (this repo):
|
||||
|
||||
```
|
||||
/
|
||||
├── CONTEXT.md
|
||||
├── docs/adr/
|
||||
│ ├── 0001-<decision>.md
|
||||
│ └── 0002-<decision>.md
|
||||
└── packages/
|
||||
```
|
||||
|
||||
(If this repo ever grows into a genuinely large multi-package monorepo, switch to the multi-context layout: a root `CONTEXT-MAP.md` pointing at a `CONTEXT.md` per package, with `docs/adr/` for system-wide decisions and per-package ADR dirs. For now one context covers everything.)
|
||||
|
||||
## Use the glossary's vocabulary
|
||||
|
||||
When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
|
||||
|
||||
If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
|
||||
|
||||
## Flag ADR conflicts
|
||||
|
||||
If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
|
||||
|
||||
> _Contradicts ADR-0001 (<decision>) — but worth reopening because…_
|
||||
@@ -0,0 +1,56 @@
|
||||
# Issue tracker: Plane
|
||||
|
||||
Issues and specs for this repo live as **work items** in the **`pi-extensions`** project (`PIEXTENSIO`) on Plane. Use the **Plane MCP tools** for all operations — these are available to skills running in this repo. There is no `gh` / git-remote coupling; Plane is independent of this repo's GitHub remote.
|
||||
|
||||
## Project & workspace
|
||||
|
||||
- **Project**: `pi-extensions` — identifier `PIEXTENSIO`, id `270cee3f-cf84-48c8-bd4f-0882689f2a87`.
|
||||
- All new issues go into this project. Look the id up with `plane_list_projects` if it ever changes.
|
||||
|
||||
## State vocabulary
|
||||
|
||||
States in this project (reference by name; resolve the id with `plane_list_states`):
|
||||
|
||||
| State | Group | Use for |
|
||||
| --------- | ---------- | --------------------------------------------- |
|
||||
| Backlog | backlog | default landing state for new issues |
|
||||
| Todo | unstarted | accepted, queued for work |
|
||||
| In Progress | started | actively being worked |
|
||||
| Done | completed | finished |
|
||||
| Cancelled | cancelled | discarded / wontfix-via-state |
|
||||
|
||||
A "closed" issue = `Done` or `Cancelled` (group `completed` / `cancelled`). "Open" = everything else (`plane_get_pql_reference` → `stateGroup IN openStates()`).
|
||||
|
||||
## Conventions
|
||||
|
||||
- **Create an issue**: `plane_create_work_item(project_id, name, description_html=...)`. It lands in `Backlog` by default. For triage, also attach the `needs-triage` label (create the label with `plane_create_label` on first use — none exist yet).
|
||||
- **Read an issue**: `plane_retrieve_work_item(project_id, work_item_id, expand="assignees,labels,state")` — or `plane_retrieve_work_item_by_identifier("PIEXTENSIO-<n>")` when you only have the `PIEXTENSIO-N` id.
|
||||
- **List issues**: `plane_list_work_items(project_id, pql=..., expand="labels,state")`. Resolve label/state names to ids first (`plane_list_labels`, `plane_list_states`). PQL examples: `stateGroup IN openStates()`; `priority = "high"`; `labels = "<label-uuid>"`. Call `plane_get_pql_reference` for full syntax.
|
||||
- **Search by text**: `plane_search_work_items(query="...")` — matches name, sequence id, and project identifier (not the description body).
|
||||
- **Comment on an issue**: `plane_create_work_item_comment(project_id, work_item_id, comment_html="...")`.
|
||||
- **Apply / remove a label**: `plane_manage_work_item_label(project_id, work_item_id, add_label_id=..., remove_label_id=...)` — add/remove one label without replacing the list.
|
||||
- **Change state**: `plane_update_work_item(project_id, work_item_id, state=<state-id>)`.
|
||||
- **Close**: set state to `Done` (or `Cancelled` for wontfix).
|
||||
|
||||
## Pull requests as a triage surface
|
||||
|
||||
**PRs as a request surface: no.** PRs live on GitHub (`SikongJueluo/pi-extensions`) but are **not** treated as triage tickets. Only Plane work items go through triage. Flip this to `yes` and describe the GitHub-PR flow if you ever want external PRs in the queue.
|
||||
|
||||
## When a skill says "publish to the issue tracker"
|
||||
|
||||
Create a Plane work item via `plane_create_work_item` in the `pi-extensions` project.
|
||||
|
||||
## When a skill says "fetch the relevant ticket"
|
||||
|
||||
`plane_retrieve_work_item_by_identifier("PIEXTENSIO-<n>", expand="assignees,labels,state")`, plus `plane_list_work_item_comments` to read the discussion.
|
||||
|
||||
## Wayfinding operations
|
||||
|
||||
Used by `/wayfinder`. The **map** is a single work item with **child** work items as tickets.
|
||||
|
||||
- **Map**: a single work item labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. Create with `plane_create_work_item`, then `plane_create_label(project_id, "wayfinder:map", ...)` if the label doesn't exist, then attach it.
|
||||
- **Child ticket**: a work item whose `parent` is the map — `plane_create_work_item(..., parent=<map-id>)` or `plane_update_work_item(parent=<map-id>)`. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, assign the driving dev via `plane_manage_work_item_assignee`.
|
||||
- **Blocking**: native work-item relations are gated on this workspace's plan, so use a **body-text fallback** — put `Blocked by: PIEXTENSIO-<n>, PIEXTENSIO-<n>` at the top of the child body. A ticket is unblocked when every blocker is `Done`/`Cancelled`.
|
||||
- **Frontier query**: list the map's open children via `plane_list_work_items` filtered to the map's children and `stateGroup IN openStates()`; drop any with an open `Blocked by` line or an assignee; first in created order wins.
|
||||
- **Claim**: `plane_manage_work_item_assignee(project_id, work_item_id, add_user_id=<me>)` — resolve `<me>` with `plane_get_me`. The session's first write.
|
||||
- **Resolve**: `plane_create_work_item_comment` with the answer, then `plane_update_work_item(state=<Done-id>)`, then append a context pointer (gist + link) to the map's Decisions-so-far (edit the map's description via `plane_update_work_item`).
|
||||
@@ -0,0 +1,19 @@
|
||||
# Triage Labels
|
||||
|
||||
The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker (Plane, project `pi-extensions` / `PIEXTENSIO`).
|
||||
|
||||
| Label in mattpocock/skills | Label in our tracker | Meaning |
|
||||
| -------------------------- | -------------------- | ---------------------------------------- |
|
||||
| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue |
|
||||
| `needs-info` | `needs-info` | Waiting on reporter for more information |
|
||||
| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent |
|
||||
| `ready-for-human` | `ready-for-human` | Requires human implementation |
|
||||
| `wontfix` | `wontfix` | Will not be actioned |
|
||||
|
||||
When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
|
||||
|
||||
## Plane notes
|
||||
|
||||
- These labels **do not exist yet** in the `pi-extensions` project. The `triage` skill should create each label with `plane_create_label(project_id, name=...)` on first use (Plane has no predefined triage labels), then attach it with `plane_manage_work_item_label`. Resolve label names to ids via `plane_list_labels`.
|
||||
- `wontfix` can be expressed either as a label **or** by moving the work item to the `Cancelled` state — prefer the label for explicit triage intent, and state for final closure.
|
||||
- Edit the right-hand column to match any other vocabulary you adopt later.
|
||||
Reference in New Issue
Block a user