@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/spec-templates/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: spec-templates
+description: "This skill should be used when creating structured feature specifications and task tracking documents. It provides standardized templates for spec.md, tasks.md, and component.md in the knowledge-base/ directory."
+---
+
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# Spec Templates
+
+Provides templates for structured feature specifications.
+
+## When to Use
+
+- At the end of `soleur:brainstorm` to create spec.md
+- At the end of `soleur:plan` to create tasks.md
+- When starting any new feature in `knowledge-base/project/specs/`
+
+**Vocabulary.** Before committing a word that names a concept, check it against `knowledge-base/project/glossary.md` and use the sense its pointer settles; if the word is materially ambiguous and has no entry, hedge in the artifact and name the ambiguity. The instruction is stated once in [glossary-format.md](../kb-glossary/references/glossary-format.md) §The consumer pointer and is not restated here.
+
+## spec.md Template
+
+Use this template for feature specifications:
+
+```markdown
+# Feature: [name]
+
+## Problem Statement
+
+[What problem are we solving?]
+
+## Goals
+
+- [What we want to achieve]
+
+## Non-Goals
+
+- [What is explicitly out of scope]
+
+## Functional Requirements
+
+### FR1: [name]
+
+[User-facing behavior]
+
+## Technical Requirements
+
+### TR1: [name]
+
+[Architecture, performance, security considerations]
+```
+
+For a browser-rendered webapp, the TRs include field Core Web Vitals
+observability per
+[webapp-cwv-observability.md](../plan/references/webapp-cwv-observability.md)
+— Sentry `browserTracingIntegration` + a probe-armed `tracesSampler` when a
+Sentry browser SDK is installed, else the beacon-endpoint fallback it specs.
+
+## tasks.md Template
+
+Use this template for task tracking:
+
+```markdown
+# Tasks: [name]
+
+## Phase 1: Setup
+
+- [ ] 1.1 Task description
+
+## Phase 2: Core Implementation
+
+- [ ] 2.1 Main task
+  - [ ] 2.1.1 Subtask if needed
+
+## Phase 3: Testing
+
+- [ ] 3.1 Task description
+```
+
+## Directory Structure
+
+Each feature gets its own directory:
+
+```
+knowledge-base/project/specs/feat-<name>/
+  spec.md      # Requirements (FR/TR)   — indexed in INDEX.md
+  tasks.md     # Phased task checklist  — indexed in INDEX.md
+  <anything else>                        # working state, NOT indexed
+```
+
+Only `spec.md` and `tasks.md` are listed in `knowledge-base/INDEX.md`. Every other
+file sitting **flat** in a spec directory is treated as branch-lifetime working state
+and is on disk but unindexed (ADR-174). A file you deliberately organise into a
+**subdirectory** stays indexed — that is the escape hatch for durable content. If a file here is durable knowledge rather than scratch,
+either fold it into `spec.md` or file it under the knowledge-base domain it belongs
+to — do not rely on it being discoverable through the index.
+
+## Usage Examples
+
+### Creating a spec for "user-auth" feature
+
+1. Create directory: `knowledge-base/project/specs/feat-user-auth/`
+2. Create `spec.md` using the template above
+3. Fill in Problem Statement, Goals, Non-Goals
+4. Add Functional Requirements (FR1, FR2, ...)
+5. Add Technical Requirements (TR1, TR2, ...)
+
+### Creating tasks from a spec
+
+1. Read the spec.md to understand requirements
+2. Create `tasks.md` using the template
+3. Break down each FR/TR into concrete tasks
+4. Organize into phases (Setup, Core, Testing)
+5. Use hierarchical numbering (2.1, 2.1.1, etc.)
+
+## component.md Template
+
+Use this template for project overview component documentation in `knowledge-base/project/components/`:
+
+```markdown
+---
+component: <component-name>
+updated: YYYY-MM-DD
+primary_location: <path/to/component/>
+related_locations:
+  - <other/path>
+dependencies:
+  - <other-component-name>
+---
+
+# <Component Name>
+
+[One paragraph - what this component does]
+
+## Purpose
+
+[Why this component exists and its role in the system]
+
+## Responsibilities
+
+- [Key responsibility 1]
+- [Key responsibility 2]
+
+## Key Interfaces
+
+[Public APIs, entry points, exported types]
+
+## Data Flow
+
+[How data enters and exits this component - include mermaid diagram if helpful]
+
+## Dependencies
+
+- **Internal**: [other components it uses]
+- **External**: [third-party packages]
+
+The `dependencies:` frontmatter list is the **machine-readable** form of the
+`**Internal**` line and MUST be kept in agreement with it. The prose line is
+human context; the frontmatter field is what
+[`c4-from-components.ts`](../../lib/c4-from-components.ts) parses into diagram
+edges. Emit both. A doc that names internal dependencies only in prose yields a
+diagram of disconnected boxes — see the relationship-count gate in
+[`sync.md`](../../commands/sync.md).
+
+## Examples
+
+[Usage examples with code]
+
+## Related Files
+
+- `path/to/file` - [description]
+
+## See Also
+
+- [constitution.md](../constitution.md) for coding conventions
+- [Related component](./related.md)
+```
+
+### YAML Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `component` | Yes | Kebab-case component name |
+| `updated` | Yes | Date last updated (YYYY-MM-DD) |
+| `primary_location` | Yes | Main directory/file path |
+| `related_locations` | No | Additional paths if component spans directories |
+| `dependencies` | No | Kebab-case `component` names this component uses. The machine-readable form of the `**Internal**` line; parsed into C4 diagram edges. Omit (or `[]`) when the component genuinely has none |
+| `status` | No | `active`, `deprecated` (default: active) |
+
+### Creating a component doc
+
+1. Identify the logical component (not just directory structure)
+2. Create `knowledge-base/project/components/<name>.md`
+3. Fill in frontmatter with accurate paths
+4. Document purpose, responsibilities, and interfaces
+5. Add data flow diagram if the component has complex interactions
+6. Link to related files and other components
+
+## prd.md Template
+
+Use this template for reverse-engineered Product Requirements Documents emitted by [`code-to-prd`](../code-to-prd/SKILL.md). PRDs land at `knowledge-base/product/prd/<project>-prd.md`. Section order is load-bearing — the `code-to-prd` test harness asserts every header.
+
+```markdown
+---
+project: "<package.json name, kebab-case>"
+framework: "next.js"
+generator: "code-to-prd@v1"
+generated_at: "<ISO-8601 UTC>"
+walker_count: <int>
+walker_excluded: <int>
+---
+
+# PRD — <project-name>
+
+<!-- BANNER:DUE-DILIGENCE — non-removable per code-to-prd FR7 -->
+> **Due-diligence disclaimer.** [verbatim from banner-template.md]
+
+<!-- BANNER:PII-CONFIDENTIALITY — non-removable per code-to-prd FR7 -->
+> **Confidentiality / PII notice.** [verbatim from banner-template.md]
+
+### How to Read This PRD
+
+[Redaction-token format, "redacted ≠ leaked" framing, rotation instruction.]
+
+## Overview
+
+- Project name, framework detected, walk stats.
+
+## Routes
+
+### App Router
+
+[Routes derived from `app/**/page.{tsx,jsx,ts,js}` and `app/**/route.{ts,js}`.]
+
+### Pages Router
+
+[Routes derived from `pages/**/*.{tsx,jsx,ts,js}` excluding `pages/_*`.]
+
+## State Shapes
+
+[Top-level `useState`/`useReducer`/server-component props (regex, best-effort).]
+
+## API & External Dependencies
+
+[fetch() URLs + `@/lib/api*`/`@/server/*` imports + `process.env.*` names + third-party SDK packages from `package.json`.]
+
+## Coverage Caveats
+
+### Frameworks not scanned
+### Extraction techniques used
+### Excluded by path filter
+### GDPR Art. 9 special-category disclaimer
+
+## Gap Analysis
+
+[Populated by `soleur:product:spec-flow-analyzer` Task spawn. Degraded-success leaves `SKIPPED (soleur:product:spec-flow-analyzer unavailable at <ISO-8601>)`.]
+
+---
+
+_Adapted from `alirezarezvani/claude-skills` (MIT) — see [plugins/soleur/NOTICE](../../NOTICE)._
+```
+
+### Coverage Caveats contract
+
+`## Coverage Caveats` MUST be non-empty on every emit. All four subsections are mandatory regardless of extractor coverage — even on a maximally simple input. "None" is forbidden. The four subsections (frameworks not scanned, extraction techniques, exclusion counts, Art. 9 disclaimer) are asserted by the `code-to-prd` test harness.
+
+### Banner contract
+
+Banners are **non-removable** — operator-edit of the rendered PRD is allowed, but the dual-banner block (sentinels `BANNER:DUE-DILIGENCE` + `BANNER:PII-CONFIDENTIALITY`) must remain intact. Verbatim string match enforced by the test harness.

package/skills/sync/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: sync
+description: This skill analyzes the codebase and populates the knowledge-base with conventions, patterns, and technical debt
+argument-hint: "[area: conventions|architecture|testing|debt|project|c4|domain-model|all]"
+# `/soleur:sync` also ships as plugins/soleur/commands/sync.md. Claude Code loads
+# plugin commands AND plugin skills into one slash menu, so without this the name
+# renders twice. `user-invocable: false` leaves the menu row to the command while
+# keeping this skill model-invocable — Skill(soleur:sync) must keep working.
+# Grok 1.0.40 validates plugin commands/ but does not register them as slash
+# commands. Do not flip this flag to expose the sync row there — that
+# re-duplicates Claude Code. The Grok slash row is `.grok/commands/sync.md`.
+user-invocable: false
+---
+
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+**Which harness this body is for.** Everything below the next heading is the **Devin CLI**
+entry-point shim: it addresses itself as the `/soleur:sync` slash command, resolves paths through
+`${CLAUDE_PLUGIN_ROOT}`, and names Devin's own adapter tools. The Grok block above says to run
+this document to completion; read the two together, because on a harness other than Devin the
+body below is not the thing to run:
+
+- **Claude Code** — this skill is `user-invocable: false` and the operator-facing row is
+  `plugins/soleur/commands/sync.md`. Read that file and act as its handler.
+- **Grok Build** — the slash row is `.grok/commands/sync.md`, which resolves to the same
+  `commands/sync.md`. Read that file and act as its handler. Do NOT detect the harness as Devin,
+  and do not use `run_subagent`; Grok's spawn tool is `spawn_subagent` with hyphenated agent ids.
+- **Codex** — `codex/skills/sync/SKILL.md` is the front door. Read `commands/sync.md` and act as
+  its handler, translating tools through `codex/INSTRUCTIONS.md` §Tools.
+
+In every case the AUTHORITY is `commands/sync.md`; the harness shims differ only in how they
+address the operator and which tool names they use.
+
+# /soleur:sync (Devin CLI entry point)
+
+You are the `/soleur:sync` slash command for the Soleur plugin on Devin CLI.
+
+The user's request is the optional area argument that follows `/soleur:sync` (e.g. `all`, `conventions`, `architecture`). Treat that text as `$ARGUMENTS`.
+
+1. Read `${CLAUDE_PLUGIN_ROOT}/commands/sync.md`.
+2. Follow every instruction in that file as if you were the `/soleur:sync` handler.
+3. Where the file uses `$ARGUMENTS` or `#$ARGUMENTS`, substitute the user's actual request.
+4. Do not improvise workflow steps. Run the producers and gated writes exactly as described.