Skip to content

feat(wiki): add repo-scoped LLM wiki integrated with SDD workflow - #22

Merged
robertraf merged 7 commits into
mainfrom
feat/21-wiki-integration
Apr 17, 2026
Merged

feat(wiki): add repo-scoped LLM wiki integrated with SDD workflow#22
robertraf merged 7 commits into
mainfrom
feat/21-wiki-integration

Conversation

@robertraf

Copy link
Copy Markdown
Owner

Summary

Adds a repo-scoped LLM Wiki (.wiki/) that accumulates high-value SDD artifacts — specs, plans, tasks summaries, review findings, and lessons learned — so future sessions consult prior work instead of rediscovering context. Introduces two new skills (/sdd:wiki-ingest, /sdd:wiki-close-loop) and a new Phase 7 "close-loop" that makes explicit what was already true: /ship is not the end of the workflow.

What changed

  • skills/wiki-ingest/SKILL.md — new skill with --preliminary and --final modes; writes YAML-frontmatter markdown pages, updates index.md per type section, and appends parseable entries to log.md. All ingestion is opt-in.
  • skills/wiki-ingest/scripts/wiki-init.sh — idempotent .wiki/ initializer (creates index.md, log.md, CLAUDE.md seed).
  • skills/wiki-ingest/scripts/wiki-query.sh — deterministic keyword matcher over .wiki/index.md: tokenize → drop stopwords + short tokens → rank by match count.
  • skills/wiki-close-loop/SKILL.md — new skill for post-merge consolidation. Uses gh to gather review comments and post-review commits, then delegates to /sdd:wiki-ingest --final with cross-links to the preliminary pages.
  • skills/spec/SKILL.md, skills/plan/SKILL.md — new Step 0 consults the wiki via ${CLAUDE_PLUGIN_ROOT}/skills/wiki-ingest/scripts/wiki-query.sh before interviewing. Graceful no-op when .wiki/ is absent.
  • skills/ship/SKILL.md — new Step 9 prompts to ingest spec/plan/tasks; Gotchas now flag that /ship is not terminal.
  • .claude/rules/wiki-conventions.md — full schema: frontmatter fields, naming, index.md/log.md format, matching algorithm, lifecycle.
  • .claude/rules/sdd-workflow.md — adds Phase 7 and broadens globs so the rule surfaces in affected skills.
  • CLAUDE.md — pipeline diagram now ends in /sdd:wiki-close-loop; skills table extended.
  • tests/wiki-init-tests.sh, tests/wiki-query-tests.sh — 27 shell tests (14 + 13).

Change overview

```mermaid
graph TD
SPEC[Modified: /spec] -->|Step 0: consult| Q[New: wiki-query.sh]
PLAN[Modified: /plan] -->|Step 0: consult| Q
Q --> IDX[.wiki/index.md]
SHIP[Modified: /ship] -->|Step 9: prompt| WI[New: /sdd:wiki-ingest --preliminary]
CL[New: /sdd:wiki-close-loop] --> WIF[New: /sdd:wiki-ingest --final]
WI --> INIT[New: wiki-init.sh]
WIF --> INIT
WI --> WIKI[.wiki/]
WIF --> WIKI
```

How to test

  1. Validate the skill suite:
    ```bash
    bash tests/validate-skills.sh
    ```
    Expected: 15 skills tested, 210 OK, 0 FAIL.
  2. Run the bundled shell tests:
    ```bash
    bash tests/wiki-init-tests.sh
    bash tests/wiki-query-tests.sh
    ```
    Expected: 14/14 and 13/13 passing.
  3. Dogfood end-to-end in a scratch repo:
    • Run `/spec` for a feature — confirm Step 0 runs silently when .wiki/ is absent.
    • Run through `/plan` → `/tasks` → `/implement` → `/review` → `/ship`.
    • At `/ship` Step 9, accept the ingestion prompt — verify .wiki/spec-*.md, plan-*.md, tasks-summary-*.md are created with frontmatter.
    • Run `/spec` again for a related topic — confirm the previous page is surfaced.
    • After merging, run `/sdd:wiki-close-loop` — confirm final pages are written and related: links point to the preliminary.

Breaking changes

None. Repos without .wiki/ continue to work with /spec, /plan, /ship exactly as before. Absence of the wiki is a graceful no-op everywhere.

References

Closes #21

robertraf and others added 6 commits April 17, 2026 09:45
Introduces the repo-scoped .wiki/ knowledge base with the /sdd:wiki-ingest
skill and its bundled helpers. Two modes (--preliminary for post-ship,
--final for post-merge) write SDD artifacts to structured markdown pages
with YAML frontmatter, grouped-by-type index, and append-only log. A
deterministic keyword matcher (wiki-query.sh) powers future consultation
by /spec, /plan, and /wiki:close-loop.

All ingestion is opt-in with explicit user confirmation. Content stays in
English per project conventions.

Refs #21

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Both /spec and /plan now run wiki-query.sh against keywords from the
user input before collecting requirements. Matches are presented as
reuse/extend/ignore options. Missing wiki or no matches is a silent
no-op — the skills stay usable in repos without .wiki/.

Refs #21

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Step 9 prompts the user to archive spec/plan/tasks to the repo wiki
after PR creation. Declining is a silent no-op. Gotchas now clarify
that /ship is not the end of the workflow — review, CI, and
post-merge close-loop are expected phases.

Refs #21

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Consolidates review findings, post-review commits, and user-stated
lessons into the wiki as final pages cross-linked to the preliminary
entries. Uses gh CLI to gather post-merge context. Delegates writes
to /sdd:wiki-ingest --final. Warns when invoked before merge or when
a PR was closed without merging. Nothing is written without explicit
user confirmation.

Refs #21

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds Phase 7 (close-loop) to the SDD pipeline documentation and makes
explicit that /ship is not terminal. Updates the root CLAUDE.md with
the new pipeline diagram, wiki skills in the table, and a pointer to
wiki-conventions.md. /sdd:run continues to orchestrate phases 1-6
only — close-loop stays manual by design.

Refs #21

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Review flagged three SKILL.md references to wiki-ingest scripts that
used raw relative paths (skills/wiki-ingest/scripts/…). Those only
resolve when the user happens to be working inside this repo; once
the plugin is installed from the marketplace, the scripts live in
the plugin cache and the relative path silently breaks. Switched to
${CLAUDE_PLUGIN_ROOT} which is already used for cross-skill paths
in hooks.json.

Also:
- Strengthen wiki-query ranking test with a third, single-token entry
  so the assertion actually verifies sort order (previous test was
  tautological — both candidates had the same score).
- Broaden the globs in sdd-workflow.md so the Phase 7 rule surfaces
  when editing ship/spec/plan/wiki-ingest/wiki-close-loop skills.

Refs #21

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@robertraf robertraf self-assigned this Apr 17, 2026
@robertraf robertraf added the enhancement New feature or request label Apr 17, 2026
Update the pipeline tagline to include the close-loop phase, document
the new /sdd:wiki-ingest and /sdd:wiki-close-loop skills in their own
"Knowledge Base (Wiki)" section, extend the core SDD table with row 7,
and mention the wiki-aware behavior in the sequence diagram and "when
to use what" table. Also call out explicitly that /ship is not
terminal — a frequent point of confusion the wiki docs address.

Refs #21

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@robertraf
robertraf merged commit 6501641 into main Apr 17, 2026
2 checks passed
@robertraf
robertraf deleted the feat/21-wiki-integration branch April 17, 2026 17:12
robertraf added a commit that referenced this pull request Apr 17, 2026
Bumps plugin version to 1.1.0 to reflect the wiki feature set added
in #22 (wiki-ingest, wiki-close-loop, and related changes to spec/plan/ship).

Adds a CI guard to the validate-plugin job that fails a pull request when
plugin files change (skills, agents, hooks, .claude-plugin, settings.json)
without a strictly greater semver in .claude-plugin/plugin.json. This
prevents future version-bump omissions.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
robertraf added a commit that referenced this pull request Apr 17, 2026
)

Bumps plugin version to 1.1.0 to reflect the wiki feature set added
in #22 (wiki-ingest, wiki-close-loop, and related changes to spec/plan/ship).

Adds a CI guard to the validate-plugin job that fails a pull request when
plugin files change (skills, agents, hooks, .claude-plugin, settings.json)
without a strictly greater semver in .claude-plugin/plugin.json. This
prevents future version-bump omissions.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(wiki): add repo-scoped LLM wiki integrated with SDD workflow

1 participant