@polygraph/codex-plugin 0.4.31 → 0.4.32

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "polygraph",
-  "version": "0.4.31",
+  "version": "0.4.32",
   "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
   "author": {
     "name": "Narwhal Technologies Inc",

package/agents/polygraph-init-subagent.toml

@@ -69,7 +69,8 @@ This returns:
   - `name`: Repository name
   - `repository`: Full repo name (e.g., `org/repo`)
   - `provider`: VCS provider (e.g., `GITHUB`)
-  - `description`: AI-generated description of what the repository does (may be null)
+
+Candidate entries do not include repository descriptions. For natural-language discovery, pass the user's intent in `semanticQuery` so the service can apply semantic matching internally.
 
 ### Step 2: Select Relevant Repos
 
@@ -79,8 +80,8 @@ If `selectedRepoIds` or exact repo refs were provided by the main agent, use tho
 
 Otherwise, analyze the candidates using the `userContext` to determine which repos are relevant:
 
-1. Read each repo's `description`
-2. Match repo descriptions against the `userContext` to identify relevant repos
+1. Review each repo's `repository`, `name`, `provider`, and any relationship/filter metadata returned by the tool
+2. Match those fields and any requested filters against the `userContext` to identify relevant repos
 3. Select the repos that are relevant to the task
 4. When uncertain, include all candidates
 5. When the user described the task in natural language and the result is large, re-query with `semanticQuery` set to that description
@@ -129,16 +130,16 @@ Return a structured summary in this format:
 
 ### Repositories in this session
 
-| Repo | Repository ID | Description | Relationship |
-| --- | --- | --- | --- |
-| REPO_FULL_NAME | REPOSITORY_ID | DESCRIPTION | DIRECTION (distance: N) |
+| Repo | Repository ID | Relationship |
+| --- | --- | --- |
+| REPO_FULL_NAME | REPOSITORY_ID | DIRECTION (distance: N) |
 
 ### All Candidates Discovered
 (Only include this section if `list_repos` was called)
 
-| Repo | Repository ID | Description | Selected |
-| --- | --- | --- | --- |
-| REPO_FULL_NAME | REPOSITORY_ID | DESCRIPTION | Yes/No |
+| Repo | Repository ID | Selected |
+| --- | --- | --- |
+| REPO_FULL_NAME | REPOSITORY_ID | Yes/No |
 ```
 
 ## Important Notes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polygraph/codex-plugin",
-  "version": "0.4.31",
+  "version": "0.4.32",
   "description": "AI agent skills and subagents for Polygraph multi-repo coordination",
   "license": "UNLICENSED",
   "private": false,

package/skills/polygraph/SKILL.md

@@ -29,7 +29,7 @@ Polygraph functionality is available via both MCP tools and CLI commands. Use wh
 
 | MCP Tool | CLI Equivalent | Description |
 | --- | --- | --- |
-| `list_repos` | `polygraph repo list` | Discover candidate repositories. |
+| `list_repos` | `polygraph repo list` | Discover candidate repositories. Candidate entries do not include repository descriptions; use `semanticQuery` for natural-language discovery. |
 | `start_session` | `polygraph session start --repo <ids>` | Initialize a Polygraph session with selected repositories |
 | `spawn_agent` | — | Start a new child task or send a follow-up to an active task in another repository. Input: `{ sessionId, repo, instruction, context? }`. Output: `{ taskId, message, status: 'delegated' }`. Follow-up routing is automatic: if the repo already has an active child task, the instruction is delivered to it as a follow-up message; otherwise a new child run starts. A repo has at most one active child at a time. A session resume or reconstruction is read-only context restoration; after resuming, do not use `spawn_agent` to continue changes unless the user explicitly asks for changes. |
 | `show_agent` | — | Poll flat per-child status for the session. Output: `{ children: PolygraphChildStatusItem[] }` where each item exposes `repositoryId`, `repoFullName`, `status`, `lastOutputLines`, `durationMs`, `instruction`, `agentType?`, `inputRequiredQuestion?`. `status` is an AcpRunStatus: `'created' \| 'in-progress' \| 'input-required' \| 'permission-required' \| 'completed' \| 'failed' \| 'cancelled'` (British double-L on `'cancelled'`). `inputRequiredQuestion` is populated only when `status === 'input-required'`. |
@@ -306,27 +306,9 @@ push_branch(
 
 ### Session Description Policy
 
-`description` is user-facing Polygraph session context.
+`description` is user-facing Polygraph session context. It is required for `push_branch`, `create_pr`, and `associate_pr`, and is the primary input to `update_session` (`mark_pr_ready` does not take a description).
 
-`description` is required for `push_branch`, `create_pr`, and `associate_pr`, and is the primary input to `update_session` (which takes `title` and/or `description`). (`mark_pr_ready` does not take a description.) Use the canonical structured format:
-
-```text
-Goal: <what the session is trying to accomplish>
-
-Current Progress: <what has been completed so far, including PR/session state when relevant>
-
-What Worked: <important decisions, approaches, or constraints that future agents should preserve>
-
-Next Steps: <clear next implementation steps>
-```
-
-- Do not use a one-line feature summary for final handoff or PR creation in a multi-repo session.
-- Keep it concise but durable for a future resumed agent.
-- Prefer high-level state over file-by-file changelogs.
-- Mention unresolved decisions or risks when they matter.
-- In `Next Steps`, include only next implementation steps. Do not list routine operational steps such as pushing branches, watching CI, or marking PRs ready.
-
-> **Tip (optional):** The Polygraph UI renders fenced ` ```mermaid ` blocks in the session description as diagrams. If a small diagram would genuinely clarify the session state — for example, cross-repo relationships or a sequence of changes — you may include one. Plain text remains the norm; diagrams are never required.
+**Whenever you write or update a session description, read [`reference/session-description.md`](reference/session-description.md) first.** That reference file holds the full policy: the canonical Markdown-heading template (`## Goal` / `## Current progress` / `## What worked` / `## Next steps`), the dual-audience guidance (humans in the web UI now, agents reconstructing history later), and the formatting building blocks the app renders (callouts, tables, mermaid, links, `link_reference`).
 
 ### 3. Create Draft PRs
 
@@ -636,15 +618,11 @@ get_ci_logs(
 
 ### Update Session Description
 
-Use this when the user asks to summarize progress, update the session description, capture the current state.
+Use this when the user asks to summarize progress, update the session description, or capture the current state.
 
-Before writing:
-- Read the current session details.
-- Consider the current conversation, child-agent results, PRs, pushed branches, validation, and unresolved decisions.
-- If appending a new item, read the current/latest description first and write the full replacement description with the existing items plus the new item.
-- If updating or replacing the existing last item, write the resulting state directly.
+Read [`reference/session-description.md`](reference/session-description.md) for the full update procedure (what to read before writing, how to append vs. replace) and the canonical Markdown-heading format. Then call `update_session` with the resulting summary as `description`.
 
-Write the description using the canonical structured format in the Session Description Policy. Then call `update_session` with the resulting summary as `description`.
+Be liberal about updating the session description when you make changes that affect the scope of the session, how logic flows between repos, or anything else important for posterity. Avoid updating it for small implementation details that are not relevant outside of this session. An up-to-date session description matters for maintainability.
 
 ### Print Polygraph Session Details
 

package/skills/polygraph/reference/session-description.md

@@ -0,0 +1,111 @@
+# Session Description Reference
+
+## Session Description Policy
+
+`description` is user-facing Polygraph session context.
+
+`description` is required for `push_branch`, `create_pr`, and `associate_pr`, and is the primary input to `update_session` (which takes `title` and/or `description`). (`mark_pr_ready` does not take a description.) The Polygraph web app renders the description as Markdown, so use real Markdown headings — not flat `Label:` lines. Use the canonical structured format:
+
+```markdown
+## Goal
+
+<what the session is trying to accomplish>
+
+## Current progress
+
+<what has been completed so far, including PR/session state when relevant>
+
+## What worked
+
+<important decisions, approaches, or constraints that future agents should preserve>
+
+## Next steps
+
+<clear next implementation steps>
+```
+
+- Do not use a one-line feature summary for final handoff or PR creation in a multi-repo session.
+- Keep it concise but durable for a future resumed agent.
+- Prefer high-level state over file-by-file changelogs.
+- Mention unresolved decisions or risks when they matter.
+- In `Next steps`, include only next implementation steps. Do not list routine operational steps such as pushing branches, watching CI, or marking PRs ready.
+
+## Dual audience: humans now, agents later
+
+The description has two readers, and you must write for both:
+
+1. **Humans, in the web UI** — this is the primary surface. The app renders the description as Markdown for people scanning session state.
+2. **Agents, later** — the description is also read back by agents reconstructing session history (for example, on resume). They may not have the original working tree, branch, or local environment available.
+
+Because of the second audience, write **durably**:
+
+- Avoid ephemeral or local references (paths, ports, in-progress scratch state) that won't mean anything to a later reader.
+- Don't assume the original working tree is available — describe *what* changed and *why* at a level that survives without the diff in front of you.
+- Capture decisions and constraints, not just a snapshot of the current terminal.
+
+## Formatting building blocks
+
+Plain text (headings + prose + lists) remains the norm. The blocks below are available when they genuinely add clarity — reach for them only when they earn their place.
+
+### Headings, emphasis, lists
+
+Use the `##` headings from the canonical template. Use **bold**/*italic* for emphasis, and bullet or numbered lists for enumerations. Keep nesting shallow.
+
+### Callouts (GitHub alert syntax)
+
+The app maps each callout to a status color, so pick the right type:
+
+- `> [!WARNING]` / `> [!CAUTION]` — risky migrations, destructive operations, or **required manual steps** a reader must not miss.
+- `> [!NOTE]` / `> [!IMPORTANT]` — context, rationale, or a key constraint worth highlighting.
+- `> [!TIP]` — an optional helpful pointer.
+
+```markdown
+> [!WARNING]
+> The auth migration must run before deploying the API repo, or existing sessions are invalidated.
+```
+
+### Tables (GFM)
+
+Use a GitHub-Flavored Markdown table only for genuinely tabular data. The polygraph UI already shows per-PR state so avoid that. 
+
+```markdown
+| Repo        |  Change Type        |
+| ----------- |  ------------------ |
+| org/api     |  api functionality  |
+| org/web     |  text-only          |
+```
+
+### Mermaid diagrams
+
+The app renders fenced ` ```mermaid ` blocks as diagrams. Use one only when it genuinely clarifies session state. Good uses:
+
+- Control or data flow between logic pieces across repos or system components.
+- A sequence of changes, or migration order.
+- A state machine.
+
+> [!IMPORTANT]
+> Do NOT redraw the cross-repo dependency / repository graph. The app already renders the repo-relationship graph for every session, so a repo-relationship diagram in the description is redundant.
+
+Plain text remains the norm; diagrams are optional and never required.
+
+### Code blocks and task lists
+
+Use fenced code blocks for commands, signatures, or short snippets. Use task lists (`- [ ]` / `- [x]`) when tracking discrete remaining work items.
+
+### Links
+
+- Prefer durable external URLs (e.g. GitHub PRs/issues, Linear tickets).
+- Do NOT put local or dev links in the description: `localhost`, `127.0.0.1`, and `file://` URLs do not resolve in the UI and are useless to later readers.
+- Do NOT put repo-relative file paths (`./foo.ts`, `../bar`) as links — they don't resolve in the UI.
+- To attach supplementary references (PRs, issues, other Polygraph sessions, Linear tickets), use the `link_reference` tool instead of inline links. `link_reference` is **supplementary** to the description, not a replacement for it.
+
+## Updating the session description
+
+Before writing:
+
+- Read the current session details.
+- Consider the current conversation, child-agent results, PRs, pushed branches, validation, and unresolved decisions.
+- If appending a new item, read the current/latest description first and write the full replacement description with the existing items plus the new item.
+- If updating or replacing the existing last item, write the resulting state directly.
+
+Write the description using the canonical structured format above. Then call `update_session` or one of the other tools like `create_pr` that take a description as input.