diff --git a/.agent/project-context.md b/.agent/project-context.md index 7442012..0dd6405 100644 --- a/.agent/project-context.md +++ b/.agent/project-context.md @@ -1,26 +1,31 @@ # Project Context Pack -Generated: 2026-06-25 -Root: /home/sjb/Documents/ai-workflows/skills +Generated: 2026-07-16 +Root: /home/sjb/Projects/personal/ws-sjb-skills/wt-master Working directory: . Status: fresh ## Purpose -A collection of agent skills (slash commands and behaviors) loaded into Steve Beaulac's AI coding agents. Each skill is a SKILL.md file that teaches the agent how to handle a specific task — from codebase design and TDD to Obsidian PKM workflows and forge interaction. + +A collection of agent skills (slash commands and behaviors) loaded into Steve Beaulac's AI coding agents. Each skill is a SKILL.md file that teaches the agent how to handle a specific task — from codebase design and TDD to Obsidian PKM workflows and tmux agent launching. ## Project type + - **Agent skill repository** — markdown-defined agent instructions -- Languages: Markdown (100%) +- Languages: Markdown (100%), one Bash script (detect-agent), one shell script (tmux-open) - Package managers: none - Build/test tools: none - Agent guidance: `AGENTS.md` at root, `docs/invocation.md` for invocation conventions, `docs/agents/` for issue tracker / triage labels / ADR wiki / domain docs ## Structure + ``` . ├── AGENTS.md # Top-level agent instructions for this repo ├── README.md # Project overview, lists user-invoked and model-invoked skills ├── .gitignore # Excludes docs/adr/ +├── .agent/ +│ └── project-context.md # This file ├── docs/ │ ├── invocation.md # Model-invoked vs user-invoked definitions │ ├── agents/ @@ -31,36 +36,39 @@ A collection of agent skills (slash commands and behaviors) loaded into Steve Be │ └── adr/ # ADR wiki clone (gitignored) └── common/ ├── README.md # Lists all common skills by invocation type - ├── engineering/ # Model-invoked: forge-interaction, project-context-pack; also sub-skills for codebase-design, domain-modeling, tdd, triage, etc. - ├── productivity/ # User-invoked: grill-me, handoff, writing-great-skills; Model-invoked: grilling - ├── pkm/ # User-invoked: conversation-summary, crit, knowledge-gardener, research-vault - ├── personal/ # User-invoked: pkm-curation; Model-invoked: forge-preferences - └── deprecated/ # Deprecated skills (audio-production-dispatcher, dsp-research-dispatcher, forge-*) + ├── engineering/ # Model-invoked: lsp-code-analysis, pkm-curation; User-invoked: commit-staged, implement-issue, project-context-pack, setup-skills + ├── productivity/ # (currently only README.md) + ├── pkm/ # User-invoked: conversation-summary, crit, research-vault, youtube-video-capture; Model-invoked: pkm-curation + ├── personal/ # (currently only README.md) + ├── misc/ # User-invoked: tmux-launch-agent + ├── in-progress/ # User-invoked: agent-handoff, knowledge-gardener + └── deprecated/ # Deprecated forge-* and dsp-* skills ``` ## Important files + - `AGENTS.md` — Agent entry point that describes structure, categories, and references docs -- `README.md` — Index of all skills divided into user-invoked and model-invoked (recently updated to fix broken links, add missing skills, correct invocation classification) +- `README.md` — Index of all skills divided into user-invoked and model-invoked - `docs/invocation.md` — Defines the invocation model (disable-model-invocation frontmatter key, human vs model reachability, dependency rules) - `docs/agents/` — Agent documentation for issue tracker, triage labels, ADR wiki, domain docs -- `common/engineering/project-context-pack/SKILL.md` — The currently running skill -- `common/engineering/codebase-design/SKILL.md` — Deep module design vocabulary (referenced by other skills) -- `common/engineering/domain-modeling/SKILL.md` — Domain modeling with ADRs and CONTEXT files -- `common/engineering/tdd/SKILL.md` — Test-driven development discipline -- `common/productivity/grilling/SKILL.md` — Relentless plan/design interview (model-invoked, triggers) -- `common/productivity/writing-great-skills/SKILL.md` — Reference for writing/editing skills +- `common/engineering/project-context-pack/SKILL.md` — The skill that generated this file +- `common/misc/tmux-launch-agent/SKILL.md` — Fork agent CLI into new tmux window (user-invoked) +- `common/misc/tmux-launch-agent/tmux-open` — Reusable script that opens a command in a new tmux window/session ## Commands + - Build: none - Test: none - Lint/typecheck: none - Run/dev: skills are invoked by AI agents — no server or dev command ## Entry points + - `AGENTS.md` — loaded by the AI agent as project instructions (referred to in pi's agent config) - Each `SKILL.md` under `common/` — referenced by agents via slash commands or auto-invocation ## Search and symbol notes + - All skills are `SKILL.md` files — search with `fd SKILL.md` - Bucket READMEs: `fd README.md common/` - Skills are classified as **user-invoked** (`disable-model-invocation: true` in frontmatter) or **model-invoked** (default, no frontmatter flag) @@ -68,25 +76,25 @@ A collection of agent skills (slash commands and behaviors) loaded into Steve Be - Shared reference docs live inside the owning skill's directory; other skills reach that material by invoking the skill ## Files inspected + - `AGENTS.md` — root agent instructions — fresh -- `README.md` — project overview — updated (all links fixed, missing skills added, invocation corrected) +- `README.md` — project overview and skill index — fresh - `docs/invocation.md` — invocation model definitions — fresh - `.gitignore` — excludes docs/adr/ — fresh -- `common/engineering/README.md` — engineering bucket index — updated (all engineering skills added, misclassified skills corrected) -- `common/README.md` — common bucket index — updated (links fixed, missing skills added) -- `common/productivity/README.md` — productivity bucket index — fresh (was already correct) -- `common/pkm/README.md` — pkm bucket index — updated (pkm-curation added) -- `common/personal/README.md` — personal bucket index — updated (noted both skills moved elsewhere) -- `common/deprecated/README.md` — deprecated bucket index — updated (all forge skills added) -- All `SKILL.md` files — frontmatter checked for invocation status +- `common/README.md` — common bucket index — fresh +- `common/misc/README.md` — misc bucket index — fresh +- `.agent/project-context.md` — this file (refreshed from stale 2026-06-25 version) ## Exclusions + - `.git/` — VCS data - `docs/adr/` — gitignored ADR wiki clone - `node_modules/`, `dist/`, `build/`, `target/`, `.venv/`, `__pycache__/`, `vendor/`, `coverage/` — not present, but excluded by policy +- `/home/sjb/.agents/skills/` — global install, NOT the source of truth for this repo - Binary files, large artifacts, credentials, secrets, personal data ## Navigation rules for future agents + - Start with `fd SKILL.md` to find all skills, then narrow by `fd SKILL.md common//` - To understand a skill's purpose, read its `SKILL.md` and the bucket `README.md` that indexes it - For invocation rules (user-invoked vs model-invoked), read `docs/invocation.md` @@ -95,9 +103,13 @@ A collection of agent skills (slash commands and behaviors) loaded into Steve Be - Track every inspected file in this cache - Re-read a file only when it changed, the cache is stale, or exact details are needed +## Edit boundaries + +When cwd is inside this repo, all file edits MUST be scoped to paths under the repo root (`/home/sjb/Projects/personal/ws-sjb-skills/wt-master`). Do NOT touch files under `/home/sjb/.agents/skills/` or `/home/sjb/.pi/` — those are the installed/runtime copies, not the source of truth. The global install is synced separately; this repo is where source edits happen. + ## Refresh notes + - This is a markdown-only repo with no build artifacts; refreshes are rarely needed unless skills are added or removed - To refresh, re-run `tree -a -I '.git' -L 4` and re-read any changed bucket READMEs or SKILL.md files - The `docs/adr/` directory is gitignored — if ADR data is needed, check the Gitea wiki directly -- All README.md files were updated on 2026-06-25 to fix broken links, add missing skills, and correct invocation classification - If a skill is moved between buckets, update all README.md files that reference it (root, common, source bucket, destination bucket) diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md index 3f74fcc..20035bb 100644 --- a/docs/agents/issue-tracker.md +++ b/docs/agents/issue-tracker.md @@ -4,9 +4,9 @@ Issues and PRDs for this repo live as Gitea issues. Use the `tea` CLI for all op ## Conventions -- **Create an issue**: `tea issue create --title "..." --description "..."`. Use a heredoc for multi-line descriptions. +- **Create an issue**: `tea issue create --title "..." --description "..."`. Use a heredoc for multi-line descriptions. - **Read an issue**: `tea issue --comments`. Use `-o json` for machine-readable output. -- **List issues**: `tea issue list --state open -o json` with appropriate `--labels` and `--state` filters. +- **List issues**: `tea issue list --state open -o json` with appropriate `--labels` and `--state` filters. - **Comment on an issue**: `tea comment "..."`. - **Apply / remove labels**: `tea issue edit --add-label "..."` / `--remove-label "..."`. Multiple labels can be comma-separated or by repeating the flag. - **Close**: `tea issue close `. `tea issue close` does not accept a closing comment, so post the explanation first with `tea comment "..."`, then close. @@ -15,12 +15,12 @@ Infer the repo from git remote -v — `tea` does this automatically when run ins ## Pull requests as a triage surface -**PRs as a request surface: no.** +**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_ When set to `yes`, PRs run through the same labels and states as issues, using the `tea pr` equivalents: - **Read a PR**: `tea pr --comments` and `tea api /repos/{owner}/{repo}/pulls/.diff` for the diff. -- **List external PRs for triage**: `tea pr list --state open -o json` then keep only PRs whose author is not a project member/owner. +- **List external PRs for triage**: `tea pr list --state open -o json` then keep only PRs whose author is not a project member/owner (a contributor's MR, not a maintainer's in-flight work). - **Comment / label / close**: `tea comment "..."`, `tea pr edit --add-label`/`--remove-label`, `tea pr close`. Gitea shares one number space across issues and PRs, so a bare `#42` may be either — resolve with `tea pr 42` and fall back to `tea issue 42`. @@ -39,7 +39,7 @@ Used by `/wayfinder`. The **map** is a single issue with **child** issues as tic - **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `tea issue create --label wayfinder:map`. - **Child ticket**: an issue linked to the map as a GitHub sub-issue (`tea api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #` at the top of the child body. Labels: `wayfinder:` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev. -- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `tea api --method POST /repos/{owner}/{repo}/issues//dependencies -F index= -F repo= -F owner=`, where `` is the blocker's numeric **issue number** (`tea api repos/{owner}/{repo}/issues/ --jq ".number. .repository.name, .repository.owner"`, where `.number` is the ``, `.repository.name` is the `` and `.repository.owner` is the ``. Where dependencies aren't available, fall back to a `Blocked by: #, #` line at the top of the child body. A ticket is unblocked when every blocker is closed. -- **Frontier query**: list the map's open dependencies (`tea api /repos/{owner}/{repo}/issues//dependencies | jq '.[] | select(.state = "open") .number'`, scoped to the map's sub-issues / task list), drop any with an open blocker (`list of dependencies is not empty`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins. +- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `tea api --method POST /repos/{owner}/{repo}/issues//dependencies -F index= -F repo= -F owner=`, where `` is the blocker's numeric **issue number** (`tea api repos/{owner}/{repo}/issues/ --jq ".number. .repository.name, .repository.owner"`, where `.number` is the ``, `.repository.name` is the `` and `.repository.owner` is the ``. Where dependencies aren't available, fall back to a `Blocked by: #, #` line at the top of the child body. A ticket is unblocked when every blocker is closed. +- **Frontier query**: list the map's open dependencies (`tea api /repos/{owner}/{repo}/issues//dependencies | jq '.[] | select(.state == "open") | .number'`, scoped to the map's sub-issues / task list), drop any with an open blocker (`list of dependencies is not empty`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins. - **Claim**: `tea issue edit --add-assignees @me` — the session's first write. -- **Resolve**: `tea comments ""`, then `tea issue close `, then append a context pointer (gist + link) to the map's Decisions-so-far. +- **Resolve**: `tea comment ""`, then `tea issue close `, then append a context pointer (gist + link) to the map's Decisions-so-far. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md index ab9669a..d2c95bc 100644 --- a/docs/agents/triage-labels.md +++ b/docs/agents/triage-labels.md @@ -2,14 +2,14 @@ The skills speak in terms of seven canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker. -| Label in 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 | -| `needs-review` | `needs-review` | Waiting for reviewed by a human | -| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent | -| `ready-for-human` | `ready-for-human` | Requires human implementation | -| `in-progress` | `in-progress` | Being actively worked on by a human or agents | -| `wontfix` | `wontfix` | Will not be actioned | +| Label in 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 | +| `needs-review` | `needs-review` | Waiting for review by a human | +| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent | +| `ready-for-human` | `ready-for-human` | Requires human implementation | +| `in-progress` | `in-progress` | Being actively worked on by a human or agents | +| `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. Only one triage label should be active.