diff --git a/plugins/context/repo-install/claude/commands/context.md b/plugins/context/repo-install/claude/commands/context.md index cd7d46b5..8473aa7d 100644 --- a/plugins/context/repo-install/claude/commands/context.md +++ b/plugins/context/repo-install/claude/commands/context.md @@ -240,6 +240,23 @@ Within an active Context workflow, requests include, but are not limited to: | Commit workspace results | Save selected workspace files in local Git, without pushing or including unrelated changes. | | Restore a historical workspace version | Select a saved commit, restore only the agreed workspace scope and make its sources usable again. | +### A prepared source checklist + +A reader may arrive with a filled checklist — a page listing the material, its +owners and whether the knowledge depends on it — instead of describing sources +in conversation. Read it and register from it. Never require one: material +described in conversation is equally valid. A team that wants a starting point +can copy [the source checklist](../resources/context/source-checklist.md). + +- One row is one source, and the row's note becomes the source note. +- The dependency column decides the treatment: a row marked as a dependency is + registered and pinned to a commit or version, so later changes reach the pages + that rest on it; a first-time reference is read for this round and cited in the + text, not registered. +- The owner named on a row is who to ask when a link fails or ownership is + unclear, instead of guessing. +- Report rows you cannot open or are not allowed to read; never drop one silently. + ### Where each request goes - **Sources, notes, sessions or changed upstream material:** read diff --git a/plugins/context/repo-install/claude/resources/context/source-checklist.md b/plugins/context/repo-install/claude/resources/context/source-checklist.md new file mode 100644 index 00000000..0fbf6767 --- /dev/null +++ b/plugins/context/repo-install/claude/resources/context/source-checklist.md @@ -0,0 +1,120 @@ +# Source checklist + +A page a team fills in before a knowledge base is built, so the Agent starts from +a list instead of a conversation. It is optional: material described in +conversation is registered the same way. + +Copy the template below, delete the groups you do not need, replace the example +rows, and give the Agent the page's link. + +## How to fill it in + +1. Keep one row per source, and write the link's text as the material's name. +2. Every row needs a link that opens and a single owner. +3. Choose one update dependency per row; the note at the end explains the two. +4. Leave a row in with "to confirm" after the owner when you are unsure it belongs. + +## Sources + +### Code repositories + +The repositories the knowledge is about and the ones it directly depends on. +Registered repositories are pinned to a commit and compared by diff later. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [example-org/billing-service](https://example.com/example-org/billing-service) | The service the knowledge describes | A. Rivera | Registered as a dependency | +| [example-org/billing-sdk](https://example.com/example-org/billing-sdk) | Client the service's callers use | B. Osei | Registered as a dependency | + +### Skills and plugins + +The Skills a workflow actually calls. Record the identifier and version; when the +version moves, the knowledge is rechecked. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [invoice-report-gen v1.4.0](https://example.com/skills/invoice-report-gen) | Generates the reports the guides describe | B. Osei | Registered as a dependency | +| [billing-metrics v0.9.2](https://example.com/skills/billing-metrics) | Collects the numbers quoted in the reference | C. Hart | Registered as a dependency | + +### Documents + +Design documents, specifications and one-pagers that have settled. Drafts and +open proposals are left out. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [Billing settlement design](https://example.com/docs/billing-settlement) | Goals and division of work; the basis for the guides | A. Rivera | Registered as a dependency | +| [Billing FAQ](https://example.com/docs/billing-faq) | Past questions, used to fill the reference pages | C. Hart | First-time reference | + +### Conversations + +Troubleshooting or design discussions that reached a conclusion. Write them up as +one note first, then list the note. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [Settlement incident, 2026-03-18](https://example.com/notes/settlement-incident) | How one production problem was found and fixed | C. Hart | First-time reference | +| [Scope discussion](https://example.com/notes/billing-scope) | Which repositories belong to this topic | A. Rivera | First-time reference | + +### Platforms and live sites + +Consoles, dashboards or published sites the pages need to cite. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [Billing console](https://example.com/console/billing) | Where operators do the work the guides describe | D. Lindqvist | Registered as a dependency | +| [Existing handbook](https://example.com/handbook/billing) | Already published, so it is not written twice | D. Lindqvist | First-time reference | + +### Notes and attachments + +Weekly reports, retrospectives and screenshots. They fold into the guides and +reference rather than becoming topics of their own. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [2026-03 billing weekly](https://example.com/notes/billing-weekly) | Progress, useful as background | B. Osei | First-time reference | +| [Release retrospective](https://example.com/notes/billing-retro) | Pitfalls, written into the FAQ | A. Rivera | First-time reference | + +> **Update dependency**: *Registered as a dependency* = when the source changes, +> the pages resting on it are rechecked and revised; it stays anchored to a commit +> or version. *First-time reference* = read while writing this round and cited in +> the text; later updates do not come back to it. + +## Structure + +Keep the directory closest to the knowledge base you are building, delete the +rest, then add or drop levels. + +- **Product or service knowledge base** — Overview; Getting started; Solutions by + scenario; Guides for the workflow, integration and release; Reference for + commands, fields and FAQ. +- **External manual for a platform** — Overview; Getting started with access; + Solutions by use case; Guides for daily operation and troubleshooting; + Reference for APIs, configuration and limits. +- **External manual for a tool** — Overview; Getting started with install and + first output; Guides for each workflow; How it works; Reference; Release notes. +- **On-call knowledge base** — Duty basics; Common problems by component; + Troubleshooting from symptom to action; Contacts and escalation; Past cases. +- **Business knowledge base** — Business overview; Terms and rules; End-to-end + flow; Common questions; Change log. + +## Start-up prompt + +Adjust it, then send it with the checklist's link. + +```text +I own . Research and initialise the knowledge workspace +from this checklist and produce the first round of knowledge. Keep to the +material listed here; ask me before bringing in anything else. +1. Check every link opens; register the rows marked as a dependency as sources, + pinning repositories to the current commit and recording Skill versions. List + anything you cannot open or are not allowed to read +2. Ask me about missing links, missing owners or unclear ownership; where someone + else has to confirm, reach the owner named on the row +3. Once you have read the sources, plan the directory against the structure kept + above; raise a better split with me first if you see one +4. Write in batches only after I confirm the directory, and keep every claim + traceable to its source +5. When writing is done, produce a diff report for my review; publish only after + it passes +``` diff --git a/plugins/context/repo-install/claude/skills/context-plan/SKILL.md b/plugins/context/repo-install/claude/skills/context-plan/SKILL.md index 52106ccb..0a843e76 100644 --- a/plugins/context/repo-install/claude/skills/context-plan/SKILL.md +++ b/plugins/context/repo-install/claude/skills/context-plan/SKILL.md @@ -37,7 +37,12 @@ an audience enters production; do not count registration as completed research. 1. Identify the selected project's existing `PLAN-*.md`, workspace and Git root. Reuse a matching plan. Inspect its current stage, permissions and pending work before expanding research; do not reset a live Context workflow. -2. Read [project-planning.md](references/project-planning.md). Review the existing +2. Ask once whether a prepared source checklist exists for this project, and take + its link if so: a filled checklist names each source, its owner and whether the + knowledge depends on it, which shortens inventory. The `context` Skill carries + a template under `references/source-checklist.md`. It is never required — + without one, continue and register material from the conversation. +3. Read [project-planning.md](references/project-planning.md). Review the existing knowledge workspace and relevant approved articles before grouping new material. Map overlaps, gaps and relationships between documents, repositories and pages; distinguish reuse, revision, consolidation and new coverage in the PLAN. @@ -48,11 +53,11 @@ an audience enters production; do not count registration as completed research. evidence already available; do not wait for a complete PLAN. Follow the early scope rules in project-planning.md, including previously confirmed choices. Reuse accessible local checkouts and saved research before fetching again. -3. Create or update `PLAN-YYYYMMDD-slug.md` at that project's Git root using +4. Create or update `PLAN-YYYYMMDD-slug.md` at that project's Git root using [the report template](templates/PLAN.md). Keep downloaded research under `.tmp/context-plans/YYYYMMDD-slug/`; the layout is a working convention, not a new CLI validation rule. -4. Present the first report and complete its review before production. By default, +5. Present the first report and complete its review before production. By default, obtain the user's approval; only an authorized `plan_review: delegate` override permits Agent review as described below. Resolve the reporting preference: report after all stages, or after each diff --git a/plugins/context/repo-install/codex/skills/context-plan/SKILL.md b/plugins/context/repo-install/codex/skills/context-plan/SKILL.md index 99407708..03b00910 100644 --- a/plugins/context/repo-install/codex/skills/context-plan/SKILL.md +++ b/plugins/context/repo-install/codex/skills/context-plan/SKILL.md @@ -36,7 +36,12 @@ an audience enters production; do not count registration as completed research. 1. Identify the selected project's existing `PLAN-*.md`, workspace and Git root. Reuse a matching plan. Inspect its current stage, permissions and pending work before expanding research; do not reset a live Context workflow. -2. Read [project-planning.md](references/project-planning.md). Review the existing +2. Ask once whether a prepared source checklist exists for this project, and take + its link if so: a filled checklist names each source, its owner and whether the + knowledge depends on it, which shortens inventory. The `context` Skill carries + a template under `references/source-checklist.md`. It is never required — + without one, continue and register material from the conversation. +3. Read [project-planning.md](references/project-planning.md). Review the existing knowledge workspace and relevant approved articles before grouping new material. Map overlaps, gaps and relationships between documents, repositories and pages; distinguish reuse, revision, consolidation and new coverage in the PLAN. @@ -47,11 +52,11 @@ an audience enters production; do not count registration as completed research. evidence already available; do not wait for a complete PLAN. Follow the early scope rules in project-planning.md, including previously confirmed choices. Reuse accessible local checkouts and saved research before fetching again. -3. Create or update `PLAN-YYYYMMDD-slug.md` at that project's Git root using +4. Create or update `PLAN-YYYYMMDD-slug.md` at that project's Git root using [the report template](templates/PLAN.md). Keep downloaded research under `.tmp/context-plans/YYYYMMDD-slug/`; the layout is a working convention, not a new CLI validation rule. -4. Present the first report and complete its review before production. By default, +5. Present the first report and complete its review before production. By default, obtain the user's approval; only an authorized `plan_review: delegate` override permits Agent review as described below. Resolve the reporting preference: report after all stages, or after each diff --git a/plugins/context/repo-install/codex/skills/context/SKILL.md b/plugins/context/repo-install/codex/skills/context/SKILL.md index 67b374fc..7e484729 100644 --- a/plugins/context/repo-install/codex/skills/context/SKILL.md +++ b/plugins/context/repo-install/codex/skills/context/SKILL.md @@ -238,6 +238,23 @@ Within an active Context workflow, requests include, but are not limited to: | Commit workspace results | Save selected workspace files in local Git, without pushing or including unrelated changes. | | Restore a historical workspace version | Select a saved commit, restore only the agreed workspace scope and make its sources usable again. | +### A prepared source checklist + +A reader may arrive with a filled checklist — a page listing the material, its +owners and whether the knowledge depends on it — instead of describing sources +in conversation. Read it and register from it. Never require one: material +described in conversation is equally valid. A team that wants a starting point +can copy [the source checklist](references/source-checklist.md). + +- One row is one source, and the row's note becomes the source note. +- The dependency column decides the treatment: a row marked as a dependency is + registered and pinned to a commit or version, so later changes reach the pages + that rest on it; a first-time reference is read for this round and cited in the + text, not registered. +- The owner named on a row is who to ask when a link fails or ownership is + unclear, instead of guessing. +- Report rows you cannot open or are not allowed to read; never drop one silently. + ### Where each request goes - **Sources, notes, sessions or changed upstream material:** read diff --git a/plugins/context/repo-install/codex/skills/context/references/source-checklist.md b/plugins/context/repo-install/codex/skills/context/references/source-checklist.md new file mode 100644 index 00000000..0fbf6767 --- /dev/null +++ b/plugins/context/repo-install/codex/skills/context/references/source-checklist.md @@ -0,0 +1,120 @@ +# Source checklist + +A page a team fills in before a knowledge base is built, so the Agent starts from +a list instead of a conversation. It is optional: material described in +conversation is registered the same way. + +Copy the template below, delete the groups you do not need, replace the example +rows, and give the Agent the page's link. + +## How to fill it in + +1. Keep one row per source, and write the link's text as the material's name. +2. Every row needs a link that opens and a single owner. +3. Choose one update dependency per row; the note at the end explains the two. +4. Leave a row in with "to confirm" after the owner when you are unsure it belongs. + +## Sources + +### Code repositories + +The repositories the knowledge is about and the ones it directly depends on. +Registered repositories are pinned to a commit and compared by diff later. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [example-org/billing-service](https://example.com/example-org/billing-service) | The service the knowledge describes | A. Rivera | Registered as a dependency | +| [example-org/billing-sdk](https://example.com/example-org/billing-sdk) | Client the service's callers use | B. Osei | Registered as a dependency | + +### Skills and plugins + +The Skills a workflow actually calls. Record the identifier and version; when the +version moves, the knowledge is rechecked. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [invoice-report-gen v1.4.0](https://example.com/skills/invoice-report-gen) | Generates the reports the guides describe | B. Osei | Registered as a dependency | +| [billing-metrics v0.9.2](https://example.com/skills/billing-metrics) | Collects the numbers quoted in the reference | C. Hart | Registered as a dependency | + +### Documents + +Design documents, specifications and one-pagers that have settled. Drafts and +open proposals are left out. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [Billing settlement design](https://example.com/docs/billing-settlement) | Goals and division of work; the basis for the guides | A. Rivera | Registered as a dependency | +| [Billing FAQ](https://example.com/docs/billing-faq) | Past questions, used to fill the reference pages | C. Hart | First-time reference | + +### Conversations + +Troubleshooting or design discussions that reached a conclusion. Write them up as +one note first, then list the note. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [Settlement incident, 2026-03-18](https://example.com/notes/settlement-incident) | How one production problem was found and fixed | C. Hart | First-time reference | +| [Scope discussion](https://example.com/notes/billing-scope) | Which repositories belong to this topic | A. Rivera | First-time reference | + +### Platforms and live sites + +Consoles, dashboards or published sites the pages need to cite. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [Billing console](https://example.com/console/billing) | Where operators do the work the guides describe | D. Lindqvist | Registered as a dependency | +| [Existing handbook](https://example.com/handbook/billing) | Already published, so it is not written twice | D. Lindqvist | First-time reference | + +### Notes and attachments + +Weekly reports, retrospectives and screenshots. They fold into the guides and +reference rather than becoming topics of their own. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [2026-03 billing weekly](https://example.com/notes/billing-weekly) | Progress, useful as background | B. Osei | First-time reference | +| [Release retrospective](https://example.com/notes/billing-retro) | Pitfalls, written into the FAQ | A. Rivera | First-time reference | + +> **Update dependency**: *Registered as a dependency* = when the source changes, +> the pages resting on it are rechecked and revised; it stays anchored to a commit +> or version. *First-time reference* = read while writing this round and cited in +> the text; later updates do not come back to it. + +## Structure + +Keep the directory closest to the knowledge base you are building, delete the +rest, then add or drop levels. + +- **Product or service knowledge base** — Overview; Getting started; Solutions by + scenario; Guides for the workflow, integration and release; Reference for + commands, fields and FAQ. +- **External manual for a platform** — Overview; Getting started with access; + Solutions by use case; Guides for daily operation and troubleshooting; + Reference for APIs, configuration and limits. +- **External manual for a tool** — Overview; Getting started with install and + first output; Guides for each workflow; How it works; Reference; Release notes. +- **On-call knowledge base** — Duty basics; Common problems by component; + Troubleshooting from symptom to action; Contacts and escalation; Past cases. +- **Business knowledge base** — Business overview; Terms and rules; End-to-end + flow; Common questions; Change log. + +## Start-up prompt + +Adjust it, then send it with the checklist's link. + +```text +I own . Research and initialise the knowledge workspace +from this checklist and produce the first round of knowledge. Keep to the +material listed here; ask me before bringing in anything else. +1. Check every link opens; register the rows marked as a dependency as sources, + pinning repositories to the current commit and recording Skill versions. List + anything you cannot open or are not allowed to read +2. Ask me about missing links, missing owners or unclear ownership; where someone + else has to confirm, reach the owner named on the row +3. Once you have read the sources, plan the directory against the structure kept + above; raise a better split with me first if you see one +4. Write in batches only after I confirm the directory, and keep every claim + traceable to its source +5. When writing is done, produce a diff report for my review; publish only after + it passes +``` diff --git a/plugins/context/repo-install/cursor/commands/c4a-context.md b/plugins/context/repo-install/cursor/commands/c4a-context.md index 011607c1..d0cec702 100644 --- a/plugins/context/repo-install/cursor/commands/c4a-context.md +++ b/plugins/context/repo-install/cursor/commands/c4a-context.md @@ -235,6 +235,23 @@ Within an active Context workflow, requests include, but are not limited to: | Commit workspace results | Save selected workspace files in local Git, without pushing or including unrelated changes. | | Restore a historical workspace version | Select a saved commit, restore only the agreed workspace scope and make its sources usable again. | +### A prepared source checklist + +A reader may arrive with a filled checklist — a page listing the material, its +owners and whether the knowledge depends on it — instead of describing sources +in conversation. Read it and register from it. Never require one: material +described in conversation is equally valid. A team that wants a starting point +can copy [the source checklist](../resources/context/source-checklist.md). + +- One row is one source, and the row's note becomes the source note. +- The dependency column decides the treatment: a row marked as a dependency is + registered and pinned to a commit or version, so later changes reach the pages + that rest on it; a first-time reference is read for this round and cited in the + text, not registered. +- The owner named on a row is who to ask when a link fails or ownership is + unclear, instead of guessing. +- Report rows you cannot open or are not allowed to read; never drop one silently. + ### Where each request goes - **Sources, notes, sessions or changed upstream material:** read diff --git a/plugins/context/repo-install/cursor/resources/context/source-checklist.md b/plugins/context/repo-install/cursor/resources/context/source-checklist.md new file mode 100644 index 00000000..0fbf6767 --- /dev/null +++ b/plugins/context/repo-install/cursor/resources/context/source-checklist.md @@ -0,0 +1,120 @@ +# Source checklist + +A page a team fills in before a knowledge base is built, so the Agent starts from +a list instead of a conversation. It is optional: material described in +conversation is registered the same way. + +Copy the template below, delete the groups you do not need, replace the example +rows, and give the Agent the page's link. + +## How to fill it in + +1. Keep one row per source, and write the link's text as the material's name. +2. Every row needs a link that opens and a single owner. +3. Choose one update dependency per row; the note at the end explains the two. +4. Leave a row in with "to confirm" after the owner when you are unsure it belongs. + +## Sources + +### Code repositories + +The repositories the knowledge is about and the ones it directly depends on. +Registered repositories are pinned to a commit and compared by diff later. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [example-org/billing-service](https://example.com/example-org/billing-service) | The service the knowledge describes | A. Rivera | Registered as a dependency | +| [example-org/billing-sdk](https://example.com/example-org/billing-sdk) | Client the service's callers use | B. Osei | Registered as a dependency | + +### Skills and plugins + +The Skills a workflow actually calls. Record the identifier and version; when the +version moves, the knowledge is rechecked. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [invoice-report-gen v1.4.0](https://example.com/skills/invoice-report-gen) | Generates the reports the guides describe | B. Osei | Registered as a dependency | +| [billing-metrics v0.9.2](https://example.com/skills/billing-metrics) | Collects the numbers quoted in the reference | C. Hart | Registered as a dependency | + +### Documents + +Design documents, specifications and one-pagers that have settled. Drafts and +open proposals are left out. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [Billing settlement design](https://example.com/docs/billing-settlement) | Goals and division of work; the basis for the guides | A. Rivera | Registered as a dependency | +| [Billing FAQ](https://example.com/docs/billing-faq) | Past questions, used to fill the reference pages | C. Hart | First-time reference | + +### Conversations + +Troubleshooting or design discussions that reached a conclusion. Write them up as +one note first, then list the note. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [Settlement incident, 2026-03-18](https://example.com/notes/settlement-incident) | How one production problem was found and fixed | C. Hart | First-time reference | +| [Scope discussion](https://example.com/notes/billing-scope) | Which repositories belong to this topic | A. Rivera | First-time reference | + +### Platforms and live sites + +Consoles, dashboards or published sites the pages need to cite. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [Billing console](https://example.com/console/billing) | Where operators do the work the guides describe | D. Lindqvist | Registered as a dependency | +| [Existing handbook](https://example.com/handbook/billing) | Already published, so it is not written twice | D. Lindqvist | First-time reference | + +### Notes and attachments + +Weekly reports, retrospectives and screenshots. They fold into the guides and +reference rather than becoming topics of their own. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [2026-03 billing weekly](https://example.com/notes/billing-weekly) | Progress, useful as background | B. Osei | First-time reference | +| [Release retrospective](https://example.com/notes/billing-retro) | Pitfalls, written into the FAQ | A. Rivera | First-time reference | + +> **Update dependency**: *Registered as a dependency* = when the source changes, +> the pages resting on it are rechecked and revised; it stays anchored to a commit +> or version. *First-time reference* = read while writing this round and cited in +> the text; later updates do not come back to it. + +## Structure + +Keep the directory closest to the knowledge base you are building, delete the +rest, then add or drop levels. + +- **Product or service knowledge base** — Overview; Getting started; Solutions by + scenario; Guides for the workflow, integration and release; Reference for + commands, fields and FAQ. +- **External manual for a platform** — Overview; Getting started with access; + Solutions by use case; Guides for daily operation and troubleshooting; + Reference for APIs, configuration and limits. +- **External manual for a tool** — Overview; Getting started with install and + first output; Guides for each workflow; How it works; Reference; Release notes. +- **On-call knowledge base** — Duty basics; Common problems by component; + Troubleshooting from symptom to action; Contacts and escalation; Past cases. +- **Business knowledge base** — Business overview; Terms and rules; End-to-end + flow; Common questions; Change log. + +## Start-up prompt + +Adjust it, then send it with the checklist's link. + +```text +I own . Research and initialise the knowledge workspace +from this checklist and produce the first round of knowledge. Keep to the +material listed here; ask me before bringing in anything else. +1. Check every link opens; register the rows marked as a dependency as sources, + pinning repositories to the current commit and recording Skill versions. List + anything you cannot open or are not allowed to read +2. Ask me about missing links, missing owners or unclear ownership; where someone + else has to confirm, reach the owner named on the row +3. Once you have read the sources, plan the directory against the structure kept + above; raise a better split with me first if you see one +4. Write in batches only after I confirm the directory, and keep every claim + traceable to its source +5. When writing is done, produce a diff report for my review; publish only after + it passes +``` diff --git a/plugins/context/repo-install/cursor/skills/context-plan/SKILL.md b/plugins/context/repo-install/cursor/skills/context-plan/SKILL.md index 52106ccb..0a843e76 100644 --- a/plugins/context/repo-install/cursor/skills/context-plan/SKILL.md +++ b/plugins/context/repo-install/cursor/skills/context-plan/SKILL.md @@ -37,7 +37,12 @@ an audience enters production; do not count registration as completed research. 1. Identify the selected project's existing `PLAN-*.md`, workspace and Git root. Reuse a matching plan. Inspect its current stage, permissions and pending work before expanding research; do not reset a live Context workflow. -2. Read [project-planning.md](references/project-planning.md). Review the existing +2. Ask once whether a prepared source checklist exists for this project, and take + its link if so: a filled checklist names each source, its owner and whether the + knowledge depends on it, which shortens inventory. The `context` Skill carries + a template under `references/source-checklist.md`. It is never required — + without one, continue and register material from the conversation. +3. Read [project-planning.md](references/project-planning.md). Review the existing knowledge workspace and relevant approved articles before grouping new material. Map overlaps, gaps and relationships between documents, repositories and pages; distinguish reuse, revision, consolidation and new coverage in the PLAN. @@ -48,11 +53,11 @@ an audience enters production; do not count registration as completed research. evidence already available; do not wait for a complete PLAN. Follow the early scope rules in project-planning.md, including previously confirmed choices. Reuse accessible local checkouts and saved research before fetching again. -3. Create or update `PLAN-YYYYMMDD-slug.md` at that project's Git root using +4. Create or update `PLAN-YYYYMMDD-slug.md` at that project's Git root using [the report template](templates/PLAN.md). Keep downloaded research under `.tmp/context-plans/YYYYMMDD-slug/`; the layout is a working convention, not a new CLI validation rule. -4. Present the first report and complete its review before production. By default, +5. Present the first report and complete its review before production. By default, obtain the user's approval; only an authorized `plan_review: delegate` override permits Agent review as described below. Resolve the reporting preference: report after all stages, or after each diff --git a/plugins/context/repo-install/skills/context-plan/SKILL.md b/plugins/context/repo-install/skills/context-plan/SKILL.md index 99407708..03b00910 100644 --- a/plugins/context/repo-install/skills/context-plan/SKILL.md +++ b/plugins/context/repo-install/skills/context-plan/SKILL.md @@ -36,7 +36,12 @@ an audience enters production; do not count registration as completed research. 1. Identify the selected project's existing `PLAN-*.md`, workspace and Git root. Reuse a matching plan. Inspect its current stage, permissions and pending work before expanding research; do not reset a live Context workflow. -2. Read [project-planning.md](references/project-planning.md). Review the existing +2. Ask once whether a prepared source checklist exists for this project, and take + its link if so: a filled checklist names each source, its owner and whether the + knowledge depends on it, which shortens inventory. The `context` Skill carries + a template under `references/source-checklist.md`. It is never required — + without one, continue and register material from the conversation. +3. Read [project-planning.md](references/project-planning.md). Review the existing knowledge workspace and relevant approved articles before grouping new material. Map overlaps, gaps and relationships between documents, repositories and pages; distinguish reuse, revision, consolidation and new coverage in the PLAN. @@ -47,11 +52,11 @@ an audience enters production; do not count registration as completed research. evidence already available; do not wait for a complete PLAN. Follow the early scope rules in project-planning.md, including previously confirmed choices. Reuse accessible local checkouts and saved research before fetching again. -3. Create or update `PLAN-YYYYMMDD-slug.md` at that project's Git root using +4. Create or update `PLAN-YYYYMMDD-slug.md` at that project's Git root using [the report template](templates/PLAN.md). Keep downloaded research under `.tmp/context-plans/YYYYMMDD-slug/`; the layout is a working convention, not a new CLI validation rule. -4. Present the first report and complete its review before production. By default, +5. Present the first report and complete its review before production. By default, obtain the user's approval; only an authorized `plan_review: delegate` override permits Agent review as described below. Resolve the reporting preference: report after all stages, or after each diff --git a/plugins/context/repo-install/skills/context/SKILL.md b/plugins/context/repo-install/skills/context/SKILL.md index 67b374fc..7e484729 100644 --- a/plugins/context/repo-install/skills/context/SKILL.md +++ b/plugins/context/repo-install/skills/context/SKILL.md @@ -238,6 +238,23 @@ Within an active Context workflow, requests include, but are not limited to: | Commit workspace results | Save selected workspace files in local Git, without pushing or including unrelated changes. | | Restore a historical workspace version | Select a saved commit, restore only the agreed workspace scope and make its sources usable again. | +### A prepared source checklist + +A reader may arrive with a filled checklist — a page listing the material, its +owners and whether the knowledge depends on it — instead of describing sources +in conversation. Read it and register from it. Never require one: material +described in conversation is equally valid. A team that wants a starting point +can copy [the source checklist](references/source-checklist.md). + +- One row is one source, and the row's note becomes the source note. +- The dependency column decides the treatment: a row marked as a dependency is + registered and pinned to a commit or version, so later changes reach the pages + that rest on it; a first-time reference is read for this round and cited in the + text, not registered. +- The owner named on a row is who to ask when a link fails or ownership is + unclear, instead of guessing. +- Report rows you cannot open or are not allowed to read; never drop one silently. + ### Where each request goes - **Sources, notes, sessions or changed upstream material:** read diff --git a/plugins/context/repo-install/skills/context/references/source-checklist.md b/plugins/context/repo-install/skills/context/references/source-checklist.md new file mode 100644 index 00000000..0fbf6767 --- /dev/null +++ b/plugins/context/repo-install/skills/context/references/source-checklist.md @@ -0,0 +1,120 @@ +# Source checklist + +A page a team fills in before a knowledge base is built, so the Agent starts from +a list instead of a conversation. It is optional: material described in +conversation is registered the same way. + +Copy the template below, delete the groups you do not need, replace the example +rows, and give the Agent the page's link. + +## How to fill it in + +1. Keep one row per source, and write the link's text as the material's name. +2. Every row needs a link that opens and a single owner. +3. Choose one update dependency per row; the note at the end explains the two. +4. Leave a row in with "to confirm" after the owner when you are unsure it belongs. + +## Sources + +### Code repositories + +The repositories the knowledge is about and the ones it directly depends on. +Registered repositories are pinned to a commit and compared by diff later. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [example-org/billing-service](https://example.com/example-org/billing-service) | The service the knowledge describes | A. Rivera | Registered as a dependency | +| [example-org/billing-sdk](https://example.com/example-org/billing-sdk) | Client the service's callers use | B. Osei | Registered as a dependency | + +### Skills and plugins + +The Skills a workflow actually calls. Record the identifier and version; when the +version moves, the knowledge is rechecked. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [invoice-report-gen v1.4.0](https://example.com/skills/invoice-report-gen) | Generates the reports the guides describe | B. Osei | Registered as a dependency | +| [billing-metrics v0.9.2](https://example.com/skills/billing-metrics) | Collects the numbers quoted in the reference | C. Hart | Registered as a dependency | + +### Documents + +Design documents, specifications and one-pagers that have settled. Drafts and +open proposals are left out. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [Billing settlement design](https://example.com/docs/billing-settlement) | Goals and division of work; the basis for the guides | A. Rivera | Registered as a dependency | +| [Billing FAQ](https://example.com/docs/billing-faq) | Past questions, used to fill the reference pages | C. Hart | First-time reference | + +### Conversations + +Troubleshooting or design discussions that reached a conclusion. Write them up as +one note first, then list the note. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [Settlement incident, 2026-03-18](https://example.com/notes/settlement-incident) | How one production problem was found and fixed | C. Hart | First-time reference | +| [Scope discussion](https://example.com/notes/billing-scope) | Which repositories belong to this topic | A. Rivera | First-time reference | + +### Platforms and live sites + +Consoles, dashboards or published sites the pages need to cite. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [Billing console](https://example.com/console/billing) | Where operators do the work the guides describe | D. Lindqvist | Registered as a dependency | +| [Existing handbook](https://example.com/handbook/billing) | Already published, so it is not written twice | D. Lindqvist | First-time reference | + +### Notes and attachments + +Weekly reports, retrospectives and screenshots. They fold into the guides and +reference rather than becoming topics of their own. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [2026-03 billing weekly](https://example.com/notes/billing-weekly) | Progress, useful as background | B. Osei | First-time reference | +| [Release retrospective](https://example.com/notes/billing-retro) | Pitfalls, written into the FAQ | A. Rivera | First-time reference | + +> **Update dependency**: *Registered as a dependency* = when the source changes, +> the pages resting on it are rechecked and revised; it stays anchored to a commit +> or version. *First-time reference* = read while writing this round and cited in +> the text; later updates do not come back to it. + +## Structure + +Keep the directory closest to the knowledge base you are building, delete the +rest, then add or drop levels. + +- **Product or service knowledge base** — Overview; Getting started; Solutions by + scenario; Guides for the workflow, integration and release; Reference for + commands, fields and FAQ. +- **External manual for a platform** — Overview; Getting started with access; + Solutions by use case; Guides for daily operation and troubleshooting; + Reference for APIs, configuration and limits. +- **External manual for a tool** — Overview; Getting started with install and + first output; Guides for each workflow; How it works; Reference; Release notes. +- **On-call knowledge base** — Duty basics; Common problems by component; + Troubleshooting from symptom to action; Contacts and escalation; Past cases. +- **Business knowledge base** — Business overview; Terms and rules; End-to-end + flow; Common questions; Change log. + +## Start-up prompt + +Adjust it, then send it with the checklist's link. + +```text +I own . Research and initialise the knowledge workspace +from this checklist and produce the first round of knowledge. Keep to the +material listed here; ask me before bringing in anything else. +1. Check every link opens; register the rows marked as a dependency as sources, + pinning repositories to the current commit and recording Skill versions. List + anything you cannot open or are not allowed to read +2. Ask me about missing links, missing owners or unclear ownership; where someone + else has to confirm, reach the owner named on the row +3. Once you have read the sources, plan the directory against the structure kept + above; raise a better split with me first if you see one +4. Write in batches only after I confirm the directory, and keep every claim + traceable to its source +5. When writing is done, produce a diff report for my review; publish only after + it passes +``` diff --git a/plugins/context/skills/context-plan/SKILL.md b/plugins/context/skills/context-plan/SKILL.md index 99407708..03b00910 100644 --- a/plugins/context/skills/context-plan/SKILL.md +++ b/plugins/context/skills/context-plan/SKILL.md @@ -36,7 +36,12 @@ an audience enters production; do not count registration as completed research. 1. Identify the selected project's existing `PLAN-*.md`, workspace and Git root. Reuse a matching plan. Inspect its current stage, permissions and pending work before expanding research; do not reset a live Context workflow. -2. Read [project-planning.md](references/project-planning.md). Review the existing +2. Ask once whether a prepared source checklist exists for this project, and take + its link if so: a filled checklist names each source, its owner and whether the + knowledge depends on it, which shortens inventory. The `context` Skill carries + a template under `references/source-checklist.md`. It is never required — + without one, continue and register material from the conversation. +3. Read [project-planning.md](references/project-planning.md). Review the existing knowledge workspace and relevant approved articles before grouping new material. Map overlaps, gaps and relationships between documents, repositories and pages; distinguish reuse, revision, consolidation and new coverage in the PLAN. @@ -47,11 +52,11 @@ an audience enters production; do not count registration as completed research. evidence already available; do not wait for a complete PLAN. Follow the early scope rules in project-planning.md, including previously confirmed choices. Reuse accessible local checkouts and saved research before fetching again. -3. Create or update `PLAN-YYYYMMDD-slug.md` at that project's Git root using +4. Create or update `PLAN-YYYYMMDD-slug.md` at that project's Git root using [the report template](templates/PLAN.md). Keep downloaded research under `.tmp/context-plans/YYYYMMDD-slug/`; the layout is a working convention, not a new CLI validation rule. -4. Present the first report and complete its review before production. By default, +5. Present the first report and complete its review before production. By default, obtain the user's approval; only an authorized `plan_review: delegate` override permits Agent review as described below. Resolve the reporting preference: report after all stages, or after each diff --git a/plugins/context/skills/context/SKILL.md b/plugins/context/skills/context/SKILL.md index 67b374fc..7e484729 100644 --- a/plugins/context/skills/context/SKILL.md +++ b/plugins/context/skills/context/SKILL.md @@ -238,6 +238,23 @@ Within an active Context workflow, requests include, but are not limited to: | Commit workspace results | Save selected workspace files in local Git, without pushing or including unrelated changes. | | Restore a historical workspace version | Select a saved commit, restore only the agreed workspace scope and make its sources usable again. | +### A prepared source checklist + +A reader may arrive with a filled checklist — a page listing the material, its +owners and whether the knowledge depends on it — instead of describing sources +in conversation. Read it and register from it. Never require one: material +described in conversation is equally valid. A team that wants a starting point +can copy [the source checklist](references/source-checklist.md). + +- One row is one source, and the row's note becomes the source note. +- The dependency column decides the treatment: a row marked as a dependency is + registered and pinned to a commit or version, so later changes reach the pages + that rest on it; a first-time reference is read for this round and cited in the + text, not registered. +- The owner named on a row is who to ask when a link fails or ownership is + unclear, instead of guessing. +- Report rows you cannot open or are not allowed to read; never drop one silently. + ### Where each request goes - **Sources, notes, sessions or changed upstream material:** read diff --git a/plugins/context/skills/context/references/source-checklist.md b/plugins/context/skills/context/references/source-checklist.md new file mode 100644 index 00000000..0fbf6767 --- /dev/null +++ b/plugins/context/skills/context/references/source-checklist.md @@ -0,0 +1,120 @@ +# Source checklist + +A page a team fills in before a knowledge base is built, so the Agent starts from +a list instead of a conversation. It is optional: material described in +conversation is registered the same way. + +Copy the template below, delete the groups you do not need, replace the example +rows, and give the Agent the page's link. + +## How to fill it in + +1. Keep one row per source, and write the link's text as the material's name. +2. Every row needs a link that opens and a single owner. +3. Choose one update dependency per row; the note at the end explains the two. +4. Leave a row in with "to confirm" after the owner when you are unsure it belongs. + +## Sources + +### Code repositories + +The repositories the knowledge is about and the ones it directly depends on. +Registered repositories are pinned to a commit and compared by diff later. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [example-org/billing-service](https://example.com/example-org/billing-service) | The service the knowledge describes | A. Rivera | Registered as a dependency | +| [example-org/billing-sdk](https://example.com/example-org/billing-sdk) | Client the service's callers use | B. Osei | Registered as a dependency | + +### Skills and plugins + +The Skills a workflow actually calls. Record the identifier and version; when the +version moves, the knowledge is rechecked. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [invoice-report-gen v1.4.0](https://example.com/skills/invoice-report-gen) | Generates the reports the guides describe | B. Osei | Registered as a dependency | +| [billing-metrics v0.9.2](https://example.com/skills/billing-metrics) | Collects the numbers quoted in the reference | C. Hart | Registered as a dependency | + +### Documents + +Design documents, specifications and one-pagers that have settled. Drafts and +open proposals are left out. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [Billing settlement design](https://example.com/docs/billing-settlement) | Goals and division of work; the basis for the guides | A. Rivera | Registered as a dependency | +| [Billing FAQ](https://example.com/docs/billing-faq) | Past questions, used to fill the reference pages | C. Hart | First-time reference | + +### Conversations + +Troubleshooting or design discussions that reached a conclusion. Write them up as +one note first, then list the note. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [Settlement incident, 2026-03-18](https://example.com/notes/settlement-incident) | How one production problem was found and fixed | C. Hart | First-time reference | +| [Scope discussion](https://example.com/notes/billing-scope) | Which repositories belong to this topic | A. Rivera | First-time reference | + +### Platforms and live sites + +Consoles, dashboards or published sites the pages need to cite. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [Billing console](https://example.com/console/billing) | Where operators do the work the guides describe | D. Lindqvist | Registered as a dependency | +| [Existing handbook](https://example.com/handbook/billing) | Already published, so it is not written twice | D. Lindqvist | First-time reference | + +### Notes and attachments + +Weekly reports, retrospectives and screenshots. They fold into the guides and +reference rather than becoming topics of their own. + +| Link | What it is | Owner | Update dependency | +| --- | --- | --- | --- | +| [2026-03 billing weekly](https://example.com/notes/billing-weekly) | Progress, useful as background | B. Osei | First-time reference | +| [Release retrospective](https://example.com/notes/billing-retro) | Pitfalls, written into the FAQ | A. Rivera | First-time reference | + +> **Update dependency**: *Registered as a dependency* = when the source changes, +> the pages resting on it are rechecked and revised; it stays anchored to a commit +> or version. *First-time reference* = read while writing this round and cited in +> the text; later updates do not come back to it. + +## Structure + +Keep the directory closest to the knowledge base you are building, delete the +rest, then add or drop levels. + +- **Product or service knowledge base** — Overview; Getting started; Solutions by + scenario; Guides for the workflow, integration and release; Reference for + commands, fields and FAQ. +- **External manual for a platform** — Overview; Getting started with access; + Solutions by use case; Guides for daily operation and troubleshooting; + Reference for APIs, configuration and limits. +- **External manual for a tool** — Overview; Getting started with install and + first output; Guides for each workflow; How it works; Reference; Release notes. +- **On-call knowledge base** — Duty basics; Common problems by component; + Troubleshooting from symptom to action; Contacts and escalation; Past cases. +- **Business knowledge base** — Business overview; Terms and rules; End-to-end + flow; Common questions; Change log. + +## Start-up prompt + +Adjust it, then send it with the checklist's link. + +```text +I own . Research and initialise the knowledge workspace +from this checklist and produce the first round of knowledge. Keep to the +material listed here; ask me before bringing in anything else. +1. Check every link opens; register the rows marked as a dependency as sources, + pinning repositories to the current commit and recording Skill versions. List + anything you cannot open or are not allowed to read +2. Ask me about missing links, missing owners or unclear ownership; where someone + else has to confirm, reach the owner named on the row +3. Once you have read the sources, plan the directory against the structure kept + above; raise a better split with me first if you see one +4. Write in batches only after I confirm the directory, and keep every claim + traceable to its source +5. When writing is done, produce a diff report for my review; publish only after + it passes +```