docs(connectors): compact tag guidance

[bcdonadio]

Summary

Reduce recurring generated-agent context by replacing store-option alias exposition with one concrete canonical command and five basic tag conventions derived from project memory.

Changes

• teach generated rules one repeated --tag store invocation and omit --tags alias mechanics
• document the basic type:, project:, scope:, source:, and priority: conventions
• canonically define the history-derived connector, hook, and Codecov scopes and regression-test schema alignment
• add a patch changeset

How to validate

1. Run npm run test:ci and confirm 100% statements, branches, functions, and lines.
2. Run npm run typecheck, npm run lint, and npm run build.
3. Install the generated Codex rules connector and confirm its managed block matches generateRulesContent() exactly without --tags or alias prose.

Risk / rollout

• Risk: Low; this changes generated agent guidance and canonical tag documentation, not CLI parsing or storage behavior.
• Rollout: Existing installations receive the compact block on the next rules connector install; rollback is the single merge commit.

Notes

• User-facing CLI help and documentation continue to describe both accepted option spellings.
• Release notes: patch changeset included.

[qodo-code-review]

PR Summary by Qodo

Docs: compact tag conventions for generated connectors guidance

📝 Documentation 🧪 Tests ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Replace store-option alias guidance with one canonical lcm store example.
• Document default tag conventions (type, project, scope, source, priority) and add
 connector-related scopes.
• Add tests to keep generated rules content aligned with the canonical tag schema.

Diagram

graph TD
  A["Template service"] --> B["Rules generator"] --> C["Command reference doc"]
  B --> D["Generated rules block"]
  E["Tag schema doc"] --> F["Template tests"] --> D
  subgraph Legend
    direction LR
    _svc(["Code module"]) ~~~ _doc["Markdown doc"] ~~~ _test(("Test"))
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Link to canonical tag schema instead of embedding conventions

• ➕ Avoids duplicating tag guidance across docs and generated templates
• ➕ Reduces risk of schema drift in generated content
• ➖ Generated-agent context becomes less self-contained
• ➖ Requires agents/users to follow links during execution

2. Keep alias mechanics in an 'advanced' appendix section

• ➕ Preserves completeness for power users without cluttering the primary flow
• ➕ Maintains a single source of truth for accepted flag spellings
• ➖ Still increases generated context size compared to fully removing alias prose
• ➖ Appendix might still be copied into managed blocks depending on template usage

Recommendation: The PR’s approach (one canonical store invocation + minimal default tag conventions) is appropriate for reducing generated-agent context while keeping CLI support unchanged. If drift becomes a recurring issue, consider replacing the embedded conventions with a short pointer to docs/tag-schema.md and keep the managed block ultra-compact.

Files changed (4) +37 / -6

Tests (1) +18 / -3

template-service.test.tsAssert generated rules content matches canonical tag guidance +18/-3

Assert generated rules content matches canonical tag guidance

• Updates tests to validate the new canonical store example and the presence of the Tag conventions section. Adds a schema alignment check by reading 'docs/tag-schema.md' and asserting the new scope rows exist; also asserts alias wording ('--tags', 'repeatable aliases') is absent.

test/connectors/template-service.test.ts

Documentation (2) +14 / -3

tag-schema.mdAdd connector/hook/Codecov scopes to tag schema +3/-0

Add connector/hook/Codecov scopes to tag schema

• Extends the canonical tag schema with 'scope:connectors', 'scope:hooks', and 'scope:codecov' to reflect history-derived conventions and provide stable scope vocabulary.

docs/tag-schema.md

command-reference.mdSimplify store example and add default tag conventions section +11/-3

Simplify store example and add default tag conventions section

• Replaces alias-oriented '--tag'/'--tags' explanation with a single canonical 'lcm store ... --tag ... --tag ...' example. Adds a compact 'Tag conventions' section enumerating the default 'type', 'project', 'scope', 'source', and 'priority' prefixes.

src/connectors/templates/sections/command-reference.md

Other (1) +5 / -0

compact-agent-tag-guidance.mdAdd patch changeset for compact tag guidance +5/-0

Add patch changeset for compact tag guidance

• Introduces a patch changeset documenting the shift to canonical '--tag' usage and compact tag conventions in generated agent instructions.

.changeset/compact-agent-tag-guidance.md

[Copilot]

Pull request overview

This PR compacts the generated connector “Available Commands” guidance by switching from --tag/--tags alias exposition to a single canonical lcm store example and a short “Tag conventions” section, while also formalizing a few additional canonical scope: values in the tag schema.

Changes:

• Update the generated command reference template to use a single lcm store example (no --tags alias mechanics) and add a concise “Tag conventions” section.
• Extend docs/tag-schema.md with canonical scopes for connectors, hooks, and codecov.
• Update tests to assert the new generated rules content and validate the schema contains the newly documented scopes; add a patch changeset.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
test/connectors/template-service.test.ts	Updates assertions for the new generated rules content and validates the schema includes the new scopes.
src/connectors/templates/sections/command-reference.md	Replaces alias-focused store guidance with a canonical store example and adds “Tag conventions”.
docs/tag-schema.md	Adds canonical scope tags for connectors/hooks/codecov.
.changeset/compact-agent-tag-guidance.md	Patch changeset entry describing the documentation/guidance update.

Suppressed comments (2)

src/connectors/templates/sections/command-reference.md:19

• The scope: conventions line examples omit lcm, but the store example immediately above uses scope:lcm. This can be confusing for users trying to follow the documented convention—include lcm in the examples (or change the store example to match the listed examples).

- `scope:` — Component or domain, such as `connectors`, `hooks`, or `codecov`

test/connectors/template-service.test.ts:94

• The expected scope: conventions text should stay aligned with the generated template content. If lcm is included as a scope example (to match scope:lcm in the store example), update this assertion string to match.

    expect(content).toContain('`scope:` — Component or domain, such as `connectors`, `hooks`, or `codecov`');

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can enable the Remediation agent and Qodo fixes findings in a dedicated fix PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 05f68cbb76

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (3)

src/mcp/tools/lcm-store.ts:11

• The lcm_store tool description lists "Valid prefixes" but omits memory_id, which is used elsewhere (e.g., signal:memory_used entries reference memory_id:<id>). This makes the tool schema documentation misleading for callers.

        description: "Canonical tags following the <prefix>:<value> schema (see docs/tag-schema.md). Use at least type: and one of project: or scope:. Examples: ['type:solution', 'scope:lcm', 'project:lcm', 'sprint:sp3', 'source:session']. Valid prefixes: type, scope, priority, owner, project, sprint, source, category, signal.",

docs/tag-schema.md:95

• The schema documents category:intent and category:mcp, but the runtime event extractors also emit skill and subagent categories which promote-events will persist as category:skill / category:subagent. Listing these avoids the schema drifting from what the daemon actually stores.

| Value | When to use |
|-------|-------------|
| `category:intent` | A captured user intent or requested outcome |
| `category:mcp` | MCP tool or integration activity |

test/mcp/server.test.ts:75

• This test uses a non-null assertion and directly indexes nested properties (tool!.inputSchema.properties.tags.description). If the tool definition changes, the test will throw before producing an assertion failure, making the failure harder to diagnose. Add explicit existence/type assertions before reading the nested description.

  it("lcm_store advertises the canonical category and signal prefixes", () => {
    const tool = getMcpToolDefinitions().find((t: any) => t.name === "lcm_store");
    const description = tool!.inputSchema.properties.tags.description;
    expect(description).toContain("category");
    expect(description).toContain("signal");

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/connectors/templates/sections/command-reference.md:15

• The PR description says the generated guidance should include “five basic tag conventions”, but this section documents seven (type/project/scope/source/priority/category/signal). Please align the PR description (or adjust the documented conventions) so reviewers/users aren’t misled about the scope of the change.

Use these basic conventions by default; add others as needed:

test/connectors/template-service.test.ts:116

• This test asserts the entire memory_id:<id> table row as one exact Markdown line, which is brittle (any doc reflow/wrapping or wording tweak will fail the test even if the schema meaning is unchanged). Prefer checking for a few key substrings instead of the full row text.

    expect(canonicalTagSchema).toContain(
      '| `memory_id:<id>` | The referenced promoted-memory identifier; pair with `signal:memory_used` so recall usage counting can attribute the memory |',
    );