From d6c23840f5f543ea35a39281d396213e195ee86f Mon Sep 17 00:00:00 2001 From: Arne Roomann-Kurrik Date: Wed, 30 Sep 2026 16:07:31 -0700 Subject: [PATCH] docs: select epic-named projects and link authored tasks --- archdev/SKILL.md | 34 ++++++++++++++++++++++++++-------- archdev/references/monitor.md | 33 ++++++++++++++++++++++----------- tasks/SKILL.md | 21 +++++++++++++++++++++ 3 files changed, 69 insertions(+), 19 deletions(-) diff --git a/archdev/SKILL.md b/archdev/SKILL.md index 1ca0eac..07a5ee3 100644 --- a/archdev/SKILL.md +++ b/archdev/SKILL.md @@ -164,14 +164,13 @@ Three beats, one command `log post --kind` — `start` once scope is clear, `lesson` on a reusable root cause or fix, `abandoned` for a failed approach, `done` (with the PR URL) or an `@name` `handoff` at the end. Before the first - post, find the project the work belongs to - (`archdev projects list --query ""`) and pass its ID as - `--project ` on every `archdev log post` for that work. If no - active project covers it, create one - (`archdev projects create "" --description ""`), named - for the product area or initiative, never for the PR, task, or - session. Look the project up again when a steer moves the session - to a different initiative. Re-read the stream before committing or + post, find the project for this work. For an epic, search active projects + for its exact name and matching scope; reuse that match or create it with + the epic name. Without an epic, select an active product-area or initiative + project covering the work, creating one only if none fits. Pass its ID as + `--project ` on every stream post. Never create a project per PR, task, + or session. Look it up again when the work changes scope. Re-read the stream + before committing or opening a PR. After `gh pr create` and after every push that moves a PR head, store that head's review annotations before doing anything else (see "PR review annotations" in monitor.md). @@ -195,6 +194,17 @@ Three beats, one command --sha ` lists them under `assessments`); publish the missing ones (see "Focus range seals" in monitor.md). + +For work with an epic, search active projects for that exact epic name and +confirm the scope. Reuse the matching project, or create one named for the epic +when none fits. Resolve duplicate names by scope, never by result order. Set +both `epic` and `project_id` on tasks (`tasks create/update --epic +--project `); graph previews use top-level `epic` and `project_id` on each +node. Use the same project ID on stream posts. Keep existing project IDs stable; +do not rename a broad project based on one task. Without an epic, use the +product area or initiative. These fields remain optional for older tasks and +clients; agents authoring new work should set both. + Every post carries human-readable text: structured posts add `--message ""` as the headline over the CLI-rendered payload summary. @@ -211,3 +221,11 @@ the risks you find within scope, then recompute, at most twice, before you post (monitor.md, Report and PR review annotations). No daemon, no log tailing: the model is the sensor until an event proves reliable enough to promote into the stop hook. + + +During staggered releases, check `tasks create --help` for `--project` +before authoring tasks with this guidance. If unavailable, upgrade the CLI; +do not silently omit membership. Keep project names at most 80 characters +until the deployed project schema and all participating CLI readers support +200. Do not truncate an epic to create a misleading match; defer creating +that project until those deployments are ready. diff --git a/archdev/references/monitor.md b/archdev/references/monitor.md index ffec645..2ef8f13 100644 --- a/archdev/references/monitor.md +++ b/archdev/references/monitor.md @@ -222,17 +222,20 @@ works on its own or on top of any `--event`. ### Tag every post with its project Before the first lifecycle post, find the project this work belongs to: -`"$archdev" projects list --query ""`, then read the -descriptions. Pick the project whose scope covers this work and pass its -ID as `--project ` on every `archdev log post` for that work — -notes, events, and `--kind` posts alike. The project belongs to the -work, not the session: when a steer moves you to a different initiative -(`agent.steered`), or a task turns out to sit elsewhere, look it up -again before the next post. Create a project only when no -active project fits (`"$archdev" projects create "" --description -""`), and name it for the product area or -initiative, not for the task or PR. Never create a project per PR, per -task, or per session. +`"$archdev" projects list --query ""`, then read the +descriptions. Pass its ID as `--project ` on every post, including +notes, events, and `--kind` posts. When the work changes scope, look it up +again before the next post. + +For work with an epic, search active projects for that exact epic name and +confirm the scope. Reuse the matching project, or create one named for the epic +when none fits. Resolve duplicate names by scope, never by result order. Set +both `epic` and `project_id` on tasks (`tasks create/update --epic +--project `); graph previews use top-level `epic` and `project_id` on each +node. Use the same project ID on stream posts. Keep existing project IDs stable; +do not rename a broad project based on one task. Without an epic, use the +product area or initiative. These fields remain optional for older tasks and +clients; agents authoring new work should set both. The tag lands in `metadata.project_id` beside the `pull_request` and `task_id` join keys, the key readers such as minimap file the post by. @@ -732,3 +735,11 @@ the taxonomy proves itself. session posts; subagents never post. - Never post secrets, tokens, customer data, or unreviewed private content. + + +During staggered releases, check `tasks create --help` for `--project` +before authoring tasks with this guidance. If unavailable, upgrade the CLI; +do not silently omit membership. Keep project names at most 80 characters +until the deployed project schema and all participating CLI readers support +200. Do not truncate an epic to create a misleading match; defer creating +that project until those deployments are ready. diff --git a/tasks/SKILL.md b/tasks/SKILL.md index 467db63..e3d0f28 100644 --- a/tasks/SKILL.md +++ b/tasks/SKILL.md @@ -10,6 +10,19 @@ browser handoff, feedback collection, revisions, and save verification; the human reviews the plan in the web UI. This works from any coding harness and does not require Factory, a daemon, a resident agent, or `archdev setup`. +## Epic and project membership + +Before creating Tasks, search `archdev projects list --query ""` for an +active project with the epic's exact name and the appropriate scope. Reuse it; +if none fits, create it with `archdev projects create "" --description +""`. Resolve duplicate names by scope. Set both `--epic` and `--project` +on task create/update. For graph import and review, set top-level `epic` and +`project_id` on every node. Preserve the project ID across name changes. +Without an epic, select the project by product area or initiative. Older tasks +and artifacts may omit these optional fields; new agent-authored work should +include both. Project membership does not change task visibility. + + ## 1. Connect this machine Resolve the absolute directory containing this loaded `SKILL.md`, independently @@ -455,3 +468,11 @@ user's direction on decisions and scope. 7. **Comment every status change** with why and what it unblocks. A status change with no comment is as opaque to the next person as the pause it resolved. + + +During staggered releases, check `tasks create --help` for `--project` +before authoring tasks with this guidance. If unavailable, upgrade the CLI; +do not silently omit membership. Keep project names at most 80 characters +until the deployed project schema and all participating CLI readers support +200. Do not truncate an epic to create a misleading match; defer creating +that project until those deployments are ready.