docs: refresh project context and fix agent docs typos
- Update .agent/project-context.md with new paths, structure, edit boundaries - Fix typo in issue-tracker.md: tea comments -> tea comment - Fix jq syntax: select(.state = "open") -> select(.state == "open") - Clean up triage-labels.md table formatting
This commit is contained in:
+37
-25
@@ -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/<category>/`
|
||||
- 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)
|
||||
|
||||
@@ -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 <number> --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 <number> "..."`.
|
||||
- **Apply / remove labels**: `tea issue edit <number> --add-label "..."` / `--remove-label "..."`. Multiple labels can be comma-separated or by repeating the flag.
|
||||
- **Close**: `tea issue close <number>`. `tea issue close` does not accept a closing comment, so post the explanation first with `tea comment <number> "..."`, 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 <number> --comments` and `tea api /repos/{owner}/{repo}/pulls/<number>.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 <number> "..."`, `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 #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`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/<child>/dependencies -F index=<blocker-issue-number> -F repo=<blocker-repo-name> -F owner=<bocker-owner-name>`, where `<blocker-usse-number>` is the blocker's numeric **issue number** (`tea api repos/{owner}/{repo}/issues/<n> --jq ".number. .repository.name, .repository.owner"`, where `.number` is the `<blocker-issue-number>`, `.repository.name` is the `<blocker-repo-name>` and `.repository.owner` is the `<blocker-repo-owner>`. Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` 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/<n>/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/<child>/dependencies -F index=<blocker-issue-number> -F repo=<blocker-repo-name> -F owner=<bocker-owner-name>`, where `<blocker-issue-number>` is the blocker's numeric **issue number** (`tea api repos/{owner}/{repo}/issues/<n> --jq ".number. .repository.name, .repository.owner"`, where `.number` is the `<blocker-issue-number>`, `.repository.name` is the `<blocker-repo-name>` and `.repository.owner` is the `<blocker-repo-owner>`. Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` 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/<n>/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 <n> --add-assignees @me` — the session's first write.
|
||||
- **Resolve**: `tea comments <n> "<answer>"`, then `tea issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.
|
||||
- **Resolve**: `tea comment <n> "<answer>"`, then `tea issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user