diff --git a/.agent/project-context.md b/.agent/project-context.md new file mode 100644 index 0000000..7442012 --- /dev/null +++ b/.agent/project-context.md @@ -0,0 +1,103 @@ +# Project Context Pack + +Generated: 2026-06-25 +Root: /home/sjb/Documents/ai-workflows/skills +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. + +## Project type +- **Agent skill repository** — markdown-defined agent instructions +- Languages: Markdown (100%) +- 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/ +├── docs/ +│ ├── invocation.md # Model-invoked vs user-invoked definitions +│ ├── agents/ +│ │ ├── adr-wiki.md # ADR wiki setup docs +│ │ ├── domain.md # Domain docs layout +│ │ ├── issue-tracker.md # Gitea issue tracker docs +│ │ └── triage-labels.md # Five-label triage vocabulary +│ └── 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-*) +``` + +## 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) +- `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 + +## 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) +- Dependencies between skills use prose invocation ("Run the `/grilling` skill"), not file cross-references +- 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) +- `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 + +## 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 +- 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` +- For agent-level docs (issue tracker, triage, ADR, domain), check `docs/agents/` +- Do not browse directories file-by-file; use `fd` and `rg` first +- Track every inspected file in this cache +- Re-read a file only when it changed, the cache is stale, or exact details are needed + +## 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/.gitignore b/.gitignore new file mode 100644 index 0000000..c36d5b8 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +docs/adr/ diff --git a/AGENTS.md b/AGENTS.md index 22dba56..5e5c24f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,7 +12,7 @@ Skills are organized into buckets based on where they can be used and their cate Skill are organized into categories based on their function. For example, `/common/misc/` is a bucket for miscellaneous skills that work in all CLI agents. -If we have a skill that is only relevant to a specific agent, we can put it in an agent-specific bucket. For example, if we have a skill that is only relevant to the `opencode` agent, we can put it in `/opencod/misc`. +If we have a skill that is only relevant to a specific agent, we can put it in an agent-specific bucket. For example, if we have a skill that is only relevant to the `opencode` agent, we can put it in `/opencode/misc`. ## list of categories @@ -20,10 +20,28 @@ If we have a skill that is only relevant to a specific agent, we can put it in a - `productivity/` — daily non-code workflow tools - `misc/` — kept around but rarely used - `personal/` — tied to my own setup, not promoted +- `pkm/` — personal knowledge management - `in-progress/` — drafts not yet ready to ship - `deprecated/` — no longer used - Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. Bucket `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**. Every `SKILL.md` is either user-invoked (`disable-model-invocation: true`, reachable only by the human) or model-invoked (model- or user-reachable). For the full definitions, description conventions, and why a user-invoked skill can invoke model-invoked skills but never another user-invoked one, see [docs/invocation.md](./docs/invocation.md). + +## Agent skills + +### Issue tracker + +Issues are tracked in Gitea on gitea.sagacity.ca. See `docs/agents/issue-tracker.md`. + +### Triage labels + +Five-label vocabulary with default names (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). See `docs/agents/triage-labels.md`. + +### Domain docs + +Single-context layout. See `docs/agents/domain.md`. + +### ADR wiki + +Gitea wiki at git@gitea.sagacity.ca:steve/Skills.wiki.git, cloned into docs/adr/, SSH key auth. See `docs/agents/adr-wiki.md`. diff --git a/README.md b/README.md index db37aa4..34ba919 100644 --- a/README.md +++ b/README.md @@ -7,17 +7,34 @@ A collection of agent skills (slash commands and behaviors) loaded into Steve Be - [conversation-summary](common/pkm/conversation-summary/SKILL.md) — Summarize the current AI conversation into a new Obsidian markdown note and matching transcript file. - [crit](common/pkm/crit/SKILL.md) — Brainstorm with AI using the CRIT framework to generate and evaluate ideas. - [grill-me](common/productivity/grill-me/SKILL.md) — A relentless interview to sharpen a plan or design. +- [grill-with-docs](common/engineering/grill-with-docs/SKILL.md) — A relentless interview to sharpen a plan or design, which also creates docs (ADRs and glossary) as we go. - [handoff](common/productivity/handoff/SKILL.md) — Compact the current conversation into a handoff document for another agent to pick up. +- [improve-codebase-architecture](common/engineering/improve-codebase-architecture/SKILL.md) — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. - [knowledge-gardener](common/pkm/knowledge-gardener/SKILL.md) — Run vault-aware semantic search, synthesis, note creation, linking, and Zettelkasten workflows for this Obsidian vault. -- [pkm-curation](common/personal/pkm-curation/SKILL.md) — Curate an Obsidian-style personal knowledge vault. -- [research-vault](common/pkm/research-vault/SKILL.md) — Research a topic through a one-question-at-a-time learning conversation and save a linked Obsidian research packet. +- [pkm-curation](common/pkm/pkm-curation/SKILL.md) — Curate an Obsidian-style personal knowledge vault by classifying notes, normalizing frontmatter, improving structure, extracting atomic notes, and adding meaningful wikilinks. +- [project-context-pack](common/engineering/project-context-pack/SKILL.md) — Build and refresh a bounded repo context memory file so agents use disciplined search instead of repeated browsing. +- [research-vault](common/pkm/research-vault/SKILL.md) — Research a topic through a one-question-at-a-time learning conversation, answer directly, share resources when useful, and save a linked Obsidian research packet. +- [setup-skills](common/engineering/setup-skills/SKILL.md) — Configure this repo for the engineering skills, set up its issue tracker, triage label vocabulary, and domain doc layout. +- [to-issues](common/engineering/to-issues/SKILL.md) — Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices. +- [to-prd](common/engineering/to-prd/SKILL.md) — Turn the current conversation into a PRD and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed. +- [triage](common/engineering/triage/SKILL.md) — Move issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs. - [writing-great-skills](common/productivity/writing-great-skills/SKILL.md) — Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable. +**Deprecated / user-invoked:** +- [forge-router](common/deprecated/forge-router/SKILL.md) — High-level guidance for choosing the right forge skill. + ## Model-invoked -- [audio-product-dsp](common/deprecated/audio-production-dispatcher/SKILL.md) — Dispatch audio product DSP hardware/software engineering requests to the best specialist workflow with measurable product-focused outputs. -- [forge-interaction](common/engineering/forge-interaction/SKILL.md) — Work safely with GitHub and Gitea repositories, issues, pull requests, releases, and remote forge state. -- [forge-preferences](common/personal/forge-preferences/SKILL.md) — Apply Steve's personal or project-specific GitHub/Gitea forge preferences. +- [codebase-design](common/engineering/codebase-design/SKILL.md) — Shared vocabulary for designing deep modules. +- [domain-modeling](common/engineering/domain-modeling/SKILL.md) — Build and sharpen a project's domain model. - [grilling](common/productivity/grilling/SKILL.md) — Interview the user relentlessly about a plan or design. -- [project-context-pack](common/engineering/project-context-pack/SKILL.md) — Build and refresh a bounded repo context memory file so agents use disciplined search instead of repeated browsing. -- [research-engineering](common/deprecated/dsp-research-dispatcher/SKILL.md) — Route DSP hardware and software research-engineering requests to the best specialist workflow and return a unified, decision-ready output. +- [resolving-merge-conflicts](common/engineering/resolving-merge-conflicts/SKILL.md) — Resolve an in-progress git merge/rebase conflict. +- [tdd](common/engineering/tdd/SKILL.md) — Test-driven development. + +**Deprecated / model-invoked:** +- [audio-product-dsp](common/deprecated/audio-production-dispatcher/SKILL.md) — Dispatch audio product DSP hardware/software engineering requests to the best specialist workflow with measurable product-focused outputs. +- [dsp-research-engineering](common/deprecated/dsp-research-dispatcher/SKILL.md) — Route DSP hardware and software research-engineering requests to the best specialist workflow and return a unified, decision-ready output. +- [forge-gitea](common/deprecated/forge-gitea/SKILL.md) — Work with Gitea repositories, issues, pull requests, releases, and CI. +- [forge-github](common/deprecated/forge-github/SKILL.md) — Work with GitHub repositories, issues, pull requests, releases, and CI. +- [forge-interaction](common/deprecated/forge-interaction/SKILL.md) — Work safely with GitHub and Gitea repositories, issues, pull requests, releases, and remote forge state. +- [forge-preferences](common/deprecated/forge-preferences/SKILL.md) — Apply Steve's personal or project-specific GitHub/Gitea forge preferences. diff --git a/common/README.md b/common/README.md index bfa5448..09fe443 100644 --- a/common/README.md +++ b/common/README.md @@ -7,17 +7,34 @@ Skills that work in all CLI agents. - [conversation-summary](pkm/conversation-summary/SKILL.md) — Summarize the current AI conversation into a new Obsidian markdown note and matching transcript file. - [crit](pkm/crit/SKILL.md) — Brainstorm with AI using the CRIT framework to generate and evaluate ideas. - [grill-me](productivity/grill-me/SKILL.md) — A relentless interview to sharpen a plan or design. +- [grill-with-docs](engineering/grill-with-docs/SKILL.md) — A relentless interview to sharpen a plan or design, which also creates docs (ADRs and glossary) as we go. - [handoff](productivity/handoff/SKILL.md) — Compact the current conversation into a handoff document for another agent to pick up. +- [improve-codebase-architecture](engineering/improve-codebase-architecture/SKILL.md) — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. - [knowledge-gardener](pkm/knowledge-gardener/SKILL.md) — Run vault-aware semantic search, synthesis, note creation, linking, and Zettelkasten workflows for this Obsidian vault. -- [pkm-curation](personal/pkm-curation/SKILL.md) — Curate an Obsidian-style personal knowledge vault. -- [research-vault](pkm/research-vault/SKILL.md) — Research a topic through a one-question-at-a-time learning conversation and save a linked Obsidian research packet. +- [pkm-curation](pkm/pkm-curation/SKILL.md) — Curate an Obsidian-style personal knowledge vault by classifying notes, normalizing frontmatter, improving structure, extracting atomic notes, and adding meaningful wikilinks. +- [project-context-pack](engineering/project-context-pack/SKILL.md) — Build and refresh a bounded repo context memory file so agents use disciplined search instead of repeated browsing. +- [research-vault](pkm/research-vault/SKILL.md) — Research a topic through a one-question-at-a-time learning conversation, answer directly, share resources when useful, and save a linked Obsidian research packet. +- [setup-skills](engineering/setup-skills/SKILL.md) — Configure this repo for the engineering skills, set up its issue tracker, triage label vocabulary, and domain doc layout. +- [to-issues](engineering/to-issues/SKILL.md) — Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices. +- [to-prd](engineering/to-prd/SKILL.md) — Turn the current conversation into a PRD and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed. +- [triage](engineering/triage/SKILL.md) — Move issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs. - [writing-great-skills](productivity/writing-great-skills/SKILL.md) — Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable. +**Deprecated / user-invoked:** +- [forge-router](deprecated/forge-router/SKILL.md) — High-level guidance for choosing the right forge skill. + ## Model-invoked -- [audio-product-dsp](deprecated/audio-production-dispatcher/SKILL.md) — Dispatch audio product DSP hardware/software engineering requests to the best specialist workflow with measurable product-focused outputs. -- [forge-interaction](engineering/forge-interaction/SKILL.md) — Work safely with GitHub and Gitea repositories, issues, pull requests, releases, and remote forge state. -- [forge-preferences](personal/forge-preferences/SKILL.md) — Apply Steve's personal or project-specific GitHub/Gitea forge preferences. +- [codebase-design](engineering/codebase-design/SKILL.md) — Shared vocabulary for designing deep modules. +- [domain-modeling](engineering/domain-modeling/SKILL.md) — Build and sharpen a project's domain model. - [grilling](productivity/grilling/SKILL.md) — Interview the user relentlessly about a plan or design. -- [project-context-pack](engineering/project-context-pack/SKILL.md) — Build and refresh a bounded repo context memory file so agents use disciplined search instead of repeated browsing. -- [research-engineering](deprecated/dsp-research-dispatcher/SKILL.md) — Route DSP hardware and software research-engineering requests to the best specialist workflow and return a unified, decision-ready output. +- [resolving-merge-conflicts](engineering/resolving-merge-conflicts/SKILL.md) — Resolve an in-progress git merge/rebase conflict. +- [tdd](engineering/tdd/SKILL.md) — Test-driven development. + +**Deprecated / model-invoked:** +- [audio-product-dsp](deprecated/audio-production-dispatcher/SKILL.md) — Dispatch audio product DSP hardware/software engineering requests to the best specialist workflow with measurable product-focused outputs. +- [dsp-research-engineering](deprecated/dsp-research-dispatcher/SKILL.md) — Route DSP hardware and software research-engineering requests to the best specialist workflow and return a unified, decision-ready output. +- [forge-gitea](deprecated/forge-gitea/SKILL.md) — Work with Gitea repositories, issues, pull requests, releases, and CI. +- [forge-github](deprecated/forge-github/SKILL.md) — Work with GitHub repositories, issues, pull requests, releases, and CI. +- [forge-interaction](deprecated/forge-interaction/SKILL.md) — Work safely with GitHub and Gitea repositories, issues, pull requests, releases, and remote forge state. +- [forge-preferences](deprecated/forge-preferences/SKILL.md) — Apply Steve's personal or project-specific GitHub/Gitea forge preferences. diff --git a/common/deprecated/README.md b/common/deprecated/README.md index 6df1182..e53fa66 100644 --- a/common/deprecated/README.md +++ b/common/deprecated/README.md @@ -2,9 +2,13 @@ ## User-invoked -_None yet._ +- [forge-router](forge-router/SKILL.md) — High-level guidance for choosing the right forge skill. ## Model-invoked - [audio-product-dsp](audio-production-dispatcher/SKILL.md) — Dispatch audio product DSP hardware/software engineering requests to the best specialist workflow with measurable product-focused outputs. -- [research-engineering](dsp-research-dispatcher/SKILL.md) — Route DSP hardware and software research-engineering requests to the best specialist workflow and return a unified, decision-ready output. +- [dsp-research-engineering](dsp-research-dispatcher/SKILL.md) — Route DSP hardware and software research-engineering requests to the best specialist workflow and return a unified, decision-ready output. +- [forge-gitea](forge-gitea/SKILL.md) — Work with Gitea repositories, issues, pull requests, releases, and CI. +- [forge-github](forge-github/SKILL.md) — Work with GitHub repositories, issues, pull requests, releases, and CI. +- [forge-interaction](forge-interaction/SKILL.md) — Work safely with GitHub and Gitea repositories, issues, pull requests, releases, and remote forge state. +- [forge-preferences](forge-preferences/SKILL.md) — Apply Steve's personal or project-specific GitHub/Gitea forge preferences. diff --git a/common/engineering/README.md b/common/engineering/README.md index 7267b1f..07d2256 100644 --- a/common/engineering/README.md +++ b/common/engineering/README.md @@ -2,9 +2,17 @@ ## User-invoked -_None yet._ +- [grill-with-docs](grill-with-docs/SKILL.md) — A relentless interview to sharpen a plan or design, which also creates docs (ADRs and glossary) as we go. +- [improve-codebase-architecture](improve-codebase-architecture/SKILL.md) — Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick. +- [project-context-pack](project-context-pack/SKILL.md) — Build and refresh a bounded repo context memory file so agents use disciplined search instead of repeated browsing. +- [setup-skills](setup-skills/SKILL.md) — Configure this repo for the engineering skills, set up its issue tracker, triage label vocabulary, and domain doc layout. +- [to-issues](to-issues/SKILL.md) — Break a plan, spec, or PRD into independently-grabbable issues on the project issue tracker using tracer-bullet vertical slices. +- [to-prd](to-prd/SKILL.md) — Turn the current conversation into a PRD and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed. +- [triage](triage/SKILL.md) — Move issues and external PRs through a state machine of triage roles — categorise, verify, grill if needed, and write agent-ready briefs. ## Model-invoked -- [forge-interaction](forge-interaction/SKILL.md) — Work safely with GitHub and Gitea repositories, issues, pull requests, releases, and remote forge state. -- [project-context-pack](project-context-pack/SKILL.md) — Build and refresh a bounded repo context memory file so agents use disciplined search instead of repeated browsing. +- [codebase-design](codebase-design/SKILL.md) — Shared vocabulary for designing deep modules. +- [domain-modeling](domain-modeling/SKILL.md) — Build and sharpen a project's domain model. +- [resolving-merge-conflicts](resolving-merge-conflicts/SKILL.md) — Resolve an in-progress git merge/rebase conflict. +- [tdd](tdd/SKILL.md) — Test-driven development. diff --git a/common/personal/README.md b/common/personal/README.md index b39f26e..933d47e 100644 --- a/common/personal/README.md +++ b/common/personal/README.md @@ -1,9 +1,6 @@ # Personal Skills -## User-invoked +_No skills currently live in this bucket._ -- [pkm-curation](pkm-curation/SKILL.md) — Curate an Obsidian-style personal knowledge vault. - -## Model-invoked - -- [forge-preferences](forge-preferences/SKILL.md) — Apply Steve's personal or project-specific forge preferences. +- `pkm-curation` has been moved to [pkm/pkm-curation](../pkm/pkm-curation/SKILL.md). +- `forge-preferences` has been moved to [deprecated/forge-preferences](../deprecated/forge-preferences/SKILL.md). diff --git a/common/pkm/README.md b/common/pkm/README.md index 6aa0357..39153d9 100644 --- a/common/pkm/README.md +++ b/common/pkm/README.md @@ -5,6 +5,7 @@ - [conversation-summary](conversation-summary/SKILL.md) — Summarize the current AI conversation into a new Obsidian markdown note and matching transcript file. - [crit](crit/SKILL.md) — Brainstorm with AI using the CRIT framework to generate and evaluate ideas. - [knowledge-gardener](knowledge-gardener/SKILL.md) — Run vault-aware semantic search, synthesis, note creation, linking, and Zettelkasten workflows for this Obsidian vault. +- [pkm-curation](pkm-curation/SKILL.md) — Curate an Obsidian-style personal knowledge vault by classifying notes, normalizing frontmatter, improving structure, extracting atomic notes, and adding meaningful wikilinks. - [research-vault](research-vault/SKILL.md) — Research a topic through a one-question-at-a-time learning conversation and save a linked Obsidian research packet. ## Model-invoked diff --git a/docs/agents/adr-wiki.md b/docs/agents/adr-wiki.md new file mode 100644 index 0000000..babf002 --- /dev/null +++ b/docs/agents/adr-wiki.md @@ -0,0 +1,66 @@ +# ADR Wiki + +Architecture Decision Records live on the forge wiki and are cloned into `docs/adr/` during setup. + +## Wiki URL + +``` +git@gitea.sagacity.ca:steve/Skills.wiki.git +``` + +Derived from the forge remote during `/setup-skills`. + +## Bootstrap + +On first setup, `/setup-skills` clones the wiki: + +```bash +git clone git@gitea.sagacity.ca:steve/Skills.wiki.git docs/adr/ +``` + +And adds `docs/adr/` to `.gitignore`. + +On subsequent sessions, pull the latest: + +```bash +cd docs/adr/ && git pull --rebase +``` + +## Auth + +Authentication for pushing ADR changes uses: **SSH key** + +The wiki remote uses `git@gitea.sagacity.ca:steve/Skills.wiki.git` — same SSH key used for the source repo. + +## Session-end push + +At end of every session, the agent: + +1. `cd docs/adr/ && git add -A && git commit -m "docs(adr): ADR-NNNN — "` +2. `git pull --rebase` (handle any web UI edits) +3. `git push` + +If a conflict arises during rebase, surface it to the user for resolution. + +## Commit message convention + +``` +docs(adr): add ADR-NNNN — title +docs(adr): update ADR-NNNN — reason +docs(adr): remove ADR-NNNN — superseded by ADR-NNNN +``` + +## Consumer skills + +These skills read from `docs/adr/` by relative path — the wiki clone is transparent: + +- `diagnosing-bugs` +- `tdd` +- `improve-codebase-architecture` +- `domain-modeling` +- `grill-with-docs` + +These skills may create ADRs in `docs/adr/`; the wiki push is handled at session end: + +- `domain-modeling` +- `improve-codebase-architecture` diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..305e9f6 --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,46 @@ +# 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, or +- **`CONTEXT-MAP.md`** at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic. +- **`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 creates them lazily when terms or decisions actually get resolved. + +## File structure + +**Single-context repo** (this repo): + +``` +/ +├── CONTEXT.md +├── docs/adr/ +│ ├── 0001-event-sourced-orders.md +│ └── 0002-postgres-for-write-model.md +├── src/ +└── .gitignore ← docs/adr/ ignored +``` + +## ADR lifecycle + +ADRs live on the forge wiki and are cloned into `docs/adr/` during setup (`/setup-skills`). The source repo ignores `docs/adr/` via `.gitignore`. + +- **Reading** — skills read ADRs by relative path (`docs/adr/...`) as before. The wiki clone is transparent. +- **Creating / updating** — skills write ADRs to `docs/adr/` as files. Changes accumulate in the wiki clone's local git state. +- **Pushing** — at end of session, the agent commits new/modified ADRs to the wiki clone and pushes to the forge wiki remote, using `git pull --rebase` before push to handle any concurrent web edits. +- **Commit message convention**: `docs(adr): ADR-NNNN — ` + +## 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-0007 (event-sourced orders) — but worth reopening because…_ diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..ca7ebfe --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,34 @@ +# Issue tracker: Gitea + +Issues and PRDs for this repo live as Gitea issues. Use the `tea` CLI for all operations. + +## Conventions + +- **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. +- **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. + +Infer the repo from git remote -v — `tea` does this automatically when run inside a clone. + +## Pull requests as a triage surface + +**PRs as a request surface: no.** + +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. +- **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`. + +## When a skill says "publish to the issue tracker" + +Create a Gitea issue. + +## When a skill says "fetch the relevant ticket" + +Run `tea issue --comments`. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000..520954c --- /dev/null +++ b/docs/agents/triage-labels.md @@ -0,0 +1,13 @@ +# 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. + +| 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 | +| `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.