docbridge 0.6.1 → 0.8.0

package/templates/skills/docbridge-adopt/SKILL.md

@@ -1,96 +0,0 @@
----
-name: docbridge-adopt
-description: Adopt DocBridge in an existing TypeScript, Swift, or Dart project. Use when asked to introduce DocBridge into a repository, choose docs/code scope, create or improve docbridge.config.json, and optionally wire simple CI or agent hooks.
----
-
-# docbridge-adopt
-
-Adopt DocBridge in an existing project. This skill assumes it is already
-installed in the agent environment through `docbridge init-with-agent`,
-`docbridge init`, or a manual copy into `.agents/skills/` or
-`.claude/skills/`.
-
-The goal is to make the repository ready for DocBridge links, then continue
-into an initial docs-first link-candidate pass. Do not assume a pull request.
-
-Run DocBridge with the project's native invocation: `docbridge` on `PATH`, a
-repo recipe such as `just check`, or
-`bun run /path/to/docbridge/src/cli/index.ts`.
-
-## Procedure
-
-1. **Survey the repository.** Inspect:
-   - existing `docbridge.config.json`
-   - Markdown docs structure and likely specification directories
-   - TypeScript, Swift, or Dart source structure and public API locations
-   - existing `@doc` / `@code` annotations
-   - package scripts, CI files, git hooks, and agent hooks
-
-2. **Recommend scope, then ask for confirmation.** Present concise options and
-   your recommendation for:
-   - docs scope: directories/files whose sections are likely specifications,
-     contracts, behavior, constraints, or design decisions
-   - code scope: language-keyed TypeScript, Swift, or Dart directories/files
-     whose supported declarations should be linkable
-   - CI/hook mode: if any integration should be added now
-
-   Do not ask the user to rediscover obvious facts from the repository. Show
-   your recommendation and the tradeoff, then wait for confirmation.
-
-3. **Create or improve config.**
-   - If no config exists, create `docbridge.config.json` with the confirmed
-     `include.code` and `include.docs` globs.
-   - Use the language-keyed `include.code` object. Do not write the old
-     array form; for example, use `{ "typescript": { "patterns": [...] } }`,
-     `{ "swift": { "patterns": [...] } }`, or
-     `{ "dart": { "patterns": [...] } }`.
-   - If config exists, read it, explain the current scope, propose any
-     improvement, and edit only after confirmation.
-   - Never replace a user-authored config blindly.
-
-4. **Install companion DocBridge skills.**
-   - After scope is confirmed and `docbridge.config.json` exists or has been
-     intentionally left unchanged, install the rest of the distributable
-     DocBridge skills for the same agent target.
-   - Prefer the project-native DocBridge invocation. From the project root, run
-     `docbridge init --yes --agent-target codex` for Codex,
-     `docbridge init --yes --agent-target claude` for Claude Code, or
-     `docbridge init --yes --agent-target both` for both. Use the target that
-     matches the existing `.agents/` and/or `.claude/` setup.
-   - This command should leave an existing `docbridge.config.json` unchanged
-     and copy any missing `docbridge-annotate`, `docbridge-link`,
-     `docbridge-review`, and `docbridge-sync` skill directories. Do not use
-     `--force` unless the user explicitly asks to overwrite installed skills.
-   - If the command is unavailable, explain the blocker and provide the manual
-     copy target paths from `templates/skills/docbridge-*` instead of silently
-     skipping this step.
-
-5. **Handle CI/hooks conservatively.**
-   - If the existing setup is simple and the user confirmed the mode, implement
-     it.
-   - If the setup is complex or ambiguous, provide a concrete patch plan or
-     snippet instead of editing.
-   - Prefer non-blocking awareness early in adoption unless the user requests a
-     hard gate.
-
-6. **Verify the setup.** Run `docbridge check` or the repository's equivalent.
-   If the project intentionally has no links yet, a clean zero-link result is
-   acceptable. Surface config or scanning diagnostics before proceeding.
-
-7. **Continue into initial candidate discovery.** After setup, inspect the
-   confirmed docs scope and present 5-10 high-value section candidates using
-   the `docbridge-link` rules. Candidate discovery may continue in the same
-   turn, but annotation edits still require section-level user confirmation.
-
-## Scope Rules
-
-- Prefer docs sections that state behavior, contracts, inputs/outputs,
-  constraints, user-visible behavior, or design decisions.
-- Treat README, changelogs, contribution docs, runbooks, logs, and release
-  notes as exclusions by default unless the user identifies specific sections
-  as specifications.
-- Prefer supported public API declarations as link targets. TypeScript starts
-  with top-level exported declarations; Swift and Dart also support member
-  endpoints with scanner-produced canonical IDs.
-- Do not decide project workflow policy such as branch or PR strategy. Mention
-  only what affects DocBridge adoption.

package/templates/skills/docbridge-annotate/SKILL.md

@@ -1,99 +0,0 @@
----
-name: docbridge-annotate
-description: Create bidirectional DocBridge links between supported code declarations and Markdown sections. Use when asked to link code to its specification, add @doc or @code annotations, annotate new code with docs, or fix DocBridge link diagnostics.
----
-
-# docbridge-annotate
-
-Create a DocBridge link pair: a `@doc` tag in the code documentation comment
-and a `@code` comment above the Markdown heading. A link is valid only when
-both directions exist and point at each other.
-
-Run DocBridge with the project's native invocation: `docbridge` on `PATH`, a
-repo recipe such as `just check`, or
-`bun run /path/to/docbridge/src/cli/index.ts`.
-
-## Link anatomy
-
-Code side — a `@doc` tag in the documentation comment of a supported
-declaration:
-
-```ts
-/**
- * @doc docs/auth.md#login-spec
- */
-export async function login() {}
-```
-
-```swift
-/// @doc docs/auth.md#login-spec
-public struct AuthService {
-  public func login(email: String, password: String) {}
-}
-```
-
-Markdown side — a standalone HTML comment directly above the heading of the
-section:
-
-```md
-<!-- @code src/auth/login.ts#login -->
-
-## Login Spec
-```
-
-Both targets are `file#fragment`: the file path is project-root-relative with
-`/` separators (no `./`, `../`, or absolute paths), and the fragment is
-required. Optional text after the target is allowed and ignored
-(`@doc docs/auth.md#login-spec human note`).
-
-## Rules that decide whether the link resolves
-
-- `@doc` works only on top-level exported declarations: `function`, `class`,
-  `abstract class`, `interface`, `type`, `enum`, `const enum`, `const` with a
-  single declarator, named default `function`/`class`, and their `declare`
-  forms. Anything else (anonymous default exports, multi-declarator `const`,
-  namespaces, re-exports, non-exported declarations) produces
-  `unsupported_declaration`.
-- Swift `@doc` works on supported public/open declarations and configured
-  internal declarations. Member endpoints are type-qualified and include
-  argument labels, for example `AuthService.login(email:password:)`.
-- Dart `@doc` works on supported public declarations. Member endpoints are
-  type-qualified without parameter signatures, for example
-  `AuthService.login`; setters carry a trailing `=`.
-- The code-side fragment is the scanner-produced canonical ID.
-- The doc-side fragment is the anchor generated from the ATX heading
-  (`#`–`######`): lowercase via JavaScript `toLowerCase()`, Unicode letters
-  and numbers preserved, whitespace and punctuation runs collapsed to `-`,
-  leading/trailing `-` removed. Example: `## Login Spec (v2)` →
-  `#login-spec-v2`. Setext headings have no anchors.
-- The `@code` comment must be standalone, indented at most 3 spaces, with the
-  body starting with `@code`. Blank lines between the comment and its heading
-  are fine; any other text in between makes it `dangling_code_annotation`.
-- One declaration may carry multiple `@doc` tags and one heading multiple
-  `@code` comments; each pair is an independent link.
-- Anchors must be unique within one Markdown file; symbols must be unique
-  among annotated declarations in one TypeScript file.
-
-## Procedure
-
-1. Identify the two endpoints: the exported declaration and the Markdown
-   section. If the section does not exist yet, write it first — the heading
-   text fixes the anchor.
-2. Add the `@doc` tag to the declaration's documentation comment (create the
-   documentation comment if missing), pointing at the doc file and the
-   generated heading anchor.
-3. Add the `@code` comment directly above the heading, pointing back at the
-   code file and the scanner-produced canonical ID.
-4. Verify with `docbridge check`. The link is correct only when no diagnostic
-   mentions either endpoint.
-
-## Diagnosing check failures
-
-| Diagnostic                                           | Meaning                              | Usual fix                                             |
-| ---------------------------------------------------- | ------------------------------------ | ----------------------------------------------------- |
-| `doc_file_not_found` / `code_file_not_found`         | target file not in the managed set   | fix the path, or extend `docbridge.config.json` globs |
-| `doc_anchor_not_found`                               | file found, anchor wrong             | regenerate the anchor from the exact heading text     |
-| `doc_backlink_not_found` / `code_backlink_not_found` | one direction missing                | add the missing `@code` or `@doc` side                |
-| `unsupported_declaration`                            | `@doc` on an unsupported declaration | move the tag to a supported declaration               |
-| `dangling_code_annotation`                           | text between `@code` and the heading | move the comment directly above the heading           |
-| `invalid_link_target`                                | malformed `file#fragment`            | rewrite the target per the rules above                |

package/templates/skills/docbridge-link/SKILL.md

@@ -1,80 +0,0 @@
----
-name: docbridge-link
-description: Link existing Markdown specification sections to existing supported code declarations. Use for docs-first candidate discovery, section-level confirmation, and adding @doc/@code annotations to existing projects.
----
-
-# docbridge-link
-
-Create DocBridge annotations for existing docs and code. Work docs-first: choose
-Markdown sections that look like specifications, then propose supported
-TypeScript, Swift, or Dart declarations that implement or represent each
-section.
-
-Run DocBridge with the project's native invocation: `docbridge` on `PATH`, a
-repo recipe such as `just check`, or
-`bun run /path/to/docbridge/src/cli/index.ts`.
-
-## Procedure
-
-1. **Determine docs scope.** Use the scope confirmed by `docbridge-adopt` when
-   available. Otherwise, inspect the repository and ask the user to confirm the
-   docs directories/files before proposing links.
-
-2. **Find section candidates.**
-   - Prioritize unlinked sections.
-   - Include already linked sections at lower priority when an additional link
-     may be justified.
-   - Ignore sections that are clearly prose-only, changelog entries, runbook
-     steps, or project process unless the user says they are specifications.
-
-3. **For each candidate section, propose up to three code symbols.** Base the
-   ranking on:
-   - heading text and section body
-   - exported symbol names
-   - existing JSDoc and nearby comments
-   - file paths and directory names
-   - implementation body only when the surrounding information is insufficient
-
-   Include both:
-   - why the symbol may match
-   - what remains uncertain
-
-4. **Ask for section-level decisions.** Present 5-10 section candidates at a
-   time. For each section the user can choose:
-   - adopt: select one or more code symbols to link
-   - exclude: do not link this section
-   - hold: keep undecided for later
-
-   The user may also name a symbol not in the proposed top three.
-
-5. **Classify no-match sections.** If no reasonable exported symbol exists,
-   report the likely reason instead of forcing a link:
-   - not implemented yet
-   - spans multiple symbols without a clear public representative
-   - likely stale docs
-   - not a specification section
-   - target appears internal or not exported
-
-6. **Add annotations only after confirmation.**
-   - Add `@code` directly above the Markdown heading, as the nearest comment
-     to the heading.
-   - Add `@doc` to the code declaration's documentation comment.
-   - If the declaration has no documentation comment, create a minimal one
-     containing only `@doc`, using the language's documentation comment form.
-   - If the pair already exists on one side, show it and, after confirmation,
-     add the missing backlink.
-   - Preserve existing annotations; do not replace or clean up suspicious links
-     in this skill.
-
-7. **Verify.** Run `docbridge check`, then inspect the affected links with
-   `docbridge context` or `docbridge graph --json --include-content` for the
-   changed files. Report any remaining diagnostics or semantic uncertainty.
-
-## Boundaries
-
-- Do not split Markdown sections or rename headings. If a section is too broad
-  or ambiguous, classify it as held or no-match.
-- Multiple code symbols may link to one docs section when each role is clear.
-- One code symbol may link to multiple docs sections when each section covers a
-  distinct specification aspect.
-- Do not link solely because names are similar.

package/templates/skills/docbridge-review/SKILL.md

@@ -1,62 +0,0 @@
----
-name: docbridge-review
-description: Review all existing DocBridge links for semantic validity. Use after adoption or periodically to find valid-but-wrong links, stale docs, excessive links, or ambiguous docs/code relationships.
----
-
-# docbridge-review
-
-Review the semantic validity of the entire DocBridge graph. This is not a
-change-set or pull-request review. It checks whether valid links actually
-connect a docs section to the code symbol that implements or represents that
-specification.
-
-This skill requires `docbridge graph --json --include-content`.
-
-## Procedure
-
-1. **Build the graph.**
-
-   ```sh
-   docbridge graph --json --include-content
-   ```
-
-   If the repository uses a wrapper, use the native invocation instead. Read
-   `diagnostics` first. Mechanical failures from `docbridge check` should be
-   fixed or acknowledged before relying on semantic findings.
-
-2. **Batch by docs file.** Review all links, but process them in batches:
-   - docs file is the default batch boundary
-   - split a batch further when it contains too many sections or links
-   - keep notes so repeated patterns are applied consistently across batches
-
-3. **Read both sides.**
-   - For docs nodes, use the graph range to read the full Markdown section.
-   - For code nodes, start with graph content: JSDoc plus signature. Read the
-     implementation only when necessary to judge the relationship.
-   - Compare behavior, contract, input/output, constraints, and design intent.
-
-4. **Classify findings.**
-   - High: clearly wrong link, stale docs fixed in place by a link, or a link
-     to a section that is not a specification.
-   - Medium: partial overlap, unclear representative symbol, overly broad
-     section, or multiple linked symbols with ambiguous roles.
-   - Low: cleanup opportunity, duplicate docs, excessive links, or missing
-     explanation of why multiple links are needed.
-
-5. **Report findings and fixes.** For each finding include:
-   - severity
-   - doc endpoint and code endpoint
-   - evidence from both sides
-   - recommended fix
-
-   Do not edit annotations automatically. If the user approves a fix, use
-   `docbridge-link` or `docbridge-annotate` rules to make the change.
-
-## Principles
-
-- `docbridge check` proves link mechanics; this skill reviews meaning.
-- Do not rubber-stamp links because the target resolves.
-- Do not delete annotations merely to silence uncertainty. Explain the
-  uncertainty and ask for a decision.
-- Prefer fewer, clearer links over broad many-to-many links without explicit
-  roles.

package/templates/skills/docbridge-sync/SKILL.md

@@ -1,68 +0,0 @@
----
-name: docbridge-sync
-description: Triage DocBridge related-gate findings — linked counterparts of changed files that were not themselves updated. Use when a Stop-hook message, CI comment, or docbridge related --gate run flags unchanged counterparts, to judge divergence with docbridge context and then update or justify each one.
----
-
-# docbridge-sync
-
-Resolve `docbridge related --gate` findings. A gate violation means a changed
-file has a linked counterpart that nobody updated — it does **not** mean the
-counterpart must change; it means nobody has decided yet. This skill makes
-that decision explicit, per counterpart.
-
-Run DocBridge with the project's native invocation: `docbridge` on `PATH`, a
-repo recipe such as `just related-gate`, or
-`bun run /path/to/docbridge/src/cli/index.ts`.
-
-## Procedure
-
-1. **Collect the violations.** Use the gate report you were given (Stop-hook
-   message, CI comment), or produce one over the change set:
-
-   ```sh
-   git diff --name-only HEAD | docbridge related --stdin --gate
-   ```
-
-   Each violation names a changed endpoint and its unchanged counterpart
-   endpoint.
-
-2. **Fetch the counterpart content.** If the report did not include it, run
-   the context command over the changed files; its output is the counterparts'
-   content:
-
-   ```sh
-   git diff --name-only HEAD | docbridge context --stdin
-   ```
-
-   Read the block for each flagged counterpart: the full spec section for a
-   doc counterpart, the full declaration including JSDoc for a code one.
-
-3. **Judge divergence, per counterpart.** Compare what the counterpart says
-   with what the change did:
-   - Behavior, contract, format, or constraint described by the counterpart no
-     longer matches → **update the counterpart** in the same change set.
-   - The change is internal (refactoring, comments, test-only, formatting) and
-     every documented statement still holds → **no update**, with a written
-     justification.
-   - The link itself is wrong (points at the wrong section or symbol) → fix
-     the annotation pair instead; follow the `docbridge-annotate` skill.
-
-4. **Re-run the gate** after updates. Counterparts you edited leave the
-   violation list; what remains must be covered by justifications.
-
-5. **Report every decision.** In the final response (and the PR description
-   when one exists), list each flagged counterpart with either the update made
-   or the justification. A justification must reference the counterpart's
-   actual content ("the section documents the exit codes, which this change
-   does not alter"), not just assert irrelevance.
-
-## Principles
-
-- Never silence a violation by deleting or rewriting annotations to detach
-  the link; that defeats the graph the gate protects.
-- Do not rubber-stamp: if the counterpart content was not read, the judgment
-  has no basis.
-- Updating a spec section to match changed code is a _decision about the
-  contract_, not bookkeeping — when the change contradicts an explicit
-  documented promise, surface it to the user instead of quietly rewriting the
-  promise.