diff --git a/.gitignore b/.gitignore index 5a50fb0..4da9b6c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ node_modules/ lib/ +packages/ .claude/ .agents/ OLD \ No newline at end of file diff --git a/docs/agents/skills/automatic/SKILL.md b/docs/agents/skills/automatic/SKILL.md deleted file mode 100644 index 40e558e..0000000 --- a/docs/agents/skills/automatic/SKILL.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -name: automatic -description: Execute the full workflow cycle (ideation -> plan -> tasks -> implementation -> review) without waiting for user confirmation between modes. Use only when the user explicitly requests automatic mode. Never auto-suggest or auto-enter this mode. Pause after review and ask whether to continue with wrapup or iterate. ---- - -# Instructions - -## Trigger - -Run only when the user explicitly requests `automatic` mode. -Do not auto-enter this mode. -Do not suggest this mode in startup mode prompts. - -## Objective - -Run the standard workflow end-to-end without waiting for user confirmation between internal mode transitions: - -1. `ideation` -2. `plan` -3. `tasks` -4. `implementation` -5. `review` - -Then pause. - -## Core behavior - -1. Execute each mode in sequence using the same requirements and artifact rules as the corresponding individual mode skills. -2. Keep momentum: do not stop between internal mode transitions unless blocked by missing mandatory input, hard failures, or safety constraints. -3. In ideation, always document alternatives (at least two viable routes when applicable), evaluate tradeoffs, propose the best route, and explicitly select it before entering plan mode. -4. After selecting the route, continue immediately into plan mode, then tasks mode, then implementation mode, then review mode. -5. Pause after review and ask the user to choose exactly one: - - `wrapup` - - `iterate` - -## Mandatory transition gates - -Never transition to the next mode until the current mode's required on-disk artifacts are complete. - -Before leaving each mode, enforce all checks below: - -1. Ideation -> Plan gate: - - A concrete ideation doc exists/was updated in `docs/ideas/-.md`. - - The doc contains alternatives, tradeoffs, and a clearly selected route. - -2. Plan -> Tasks gate: - - A plan doc exists/was updated in `docs/plans/-.md`. - - The plan includes architecture decisions, expected file changes, pitfalls, and explicit contracts. - - The plan is focused on the chosen route (not a list of all routes). - -3. Tasks -> Implementation gate: - - The same plan doc includes phased tasks. - - Every phase has explicit validation criteria. - - Dependency graph / parallelization notes are present. - -4. Implementation -> Review gate: - - Implementation work is executed phase by phase against the tasked plan. - - Validation for each completed phase is run and recorded. - - The plan doc is updated after each completed phase before moving on. - -If any gate check fails, stop and fix the missing artifact first. Do not implement code before the tasks gate is satisfied. - -## Artifact rules - -Use the same artifact contract as the normal workflow: - -- `ideation`: create/update `docs/ideas/-.md` -- `plan`: create/update `docs/plans/-.md` -- `tasks`: update the active plan doc with phases/tasks/validation -- `implementation`: execute phases and update the active plan doc after completed phases -- `review`: emit findings first, then update plan/docs according to resolved now-vs-future decisions - -Follow numbering and conversion rules from workflow mode. - -## Iterate loop - -If the user chooses `iterate` after review: - -1. Continue with another cycle focused on the review-identified gaps: - - ideation -> plan -> tasks -> implementation -> review -2. Reuse the same active plan document for this loop. -3. Append/refine phases/tasks in that existing plan document instead of creating a new plan file. -4. After the follow-up review, pause again and ask the same decision: - - `wrapup` - - `iterate` - -Repeat until the user selects `wrapup` or stops. - -## Handoff to wrapup - -Do not enter `wrapup` automatically. -Enter `wrapup` only after the user explicitly chooses `wrapup` at a review pause point. - -## Guardrails - -- Do not bypass required validation in implementation. -- Do not skip required artifact updates. -- Do not silently change the chosen route without documenting why. -- If critical ambiguity appears that blocks correct implementation, ask focused clarification questions, then resume automatic progression. -- If implementation was started prematurely, pause and backfill the missing plan/tasks artifacts before continuing. -- Treat missing `docs/plans` as a hard blocker for implementation mode. - -## Exit criteria - -- Reached review mode and paused with explicit `wrapup` vs `iterate` question, or -- User explicitly selected `wrapup` and control has been handed off to wrapup mode. diff --git a/docs/agents/skills/ideation/SKILL.md b/docs/agents/skills/ideation/SKILL.md deleted file mode 100644 index 4fa6ffe..0000000 --- a/docs/agents/skills/ideation/SKILL.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -name: ideation -description: Explore and compare candidate implementation routes before committing to a plan. ---- - -# Instructions - -## Objective - -Explore potential routes and architecture choices before locking in implementation direction. - -## Entry gate - -Run this mode only after the user explicitly confirms ideation mode for the current task. - -## Steps - -1. Read relevant code, tests, and docs first. -2. Create/update `docs/ideas/-.md`. - - For new ideation docs, `` MUST be the next available 3-digit prefix in `docs/ideas`. -3. For each major architecture decision, list multiple viable approaches when applicable. -4. For each approach, document tradeoffs, pros/cons, and potential risks. -5. Capture user feedback and narrow choices. - -## Guardrails - -- Do not write implementation code in this mode. -- Do not convert ideation into a plan unless the user explicitly requests it. - -## Exit criteria - -- Key decisions and route options are documented. -- User feedback has narrowed choices. -- User has explicitly confirmed whether to switch to plan mode or stay in ideation mode. diff --git a/docs/agents/skills/implementation/SKILL.md b/docs/agents/skills/implementation/SKILL.md deleted file mode 100644 index a7b8978..0000000 --- a/docs/agents/skills/implementation/SKILL.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -name: implementation -description: Execute planned tasks phase-by-phase with one commit per phase, required validation, and pause-on-deviation reporting. ---- - -# Instructions - -## Trigger - -Run only after explicit user confirmation to enter implementation mode, with an approved plan file in `docs/plans`. - -## Steps - -1. Confirm the approved plan exists on disk at `docs/plans/-.md`. Tool-native plan mode alone is not sufficient. -2. If this plan stems from an ideation doc, remove the originating ideation doc in `docs/ideas` when implementation begins. -3. Implement one planned phase at a time. -4. Run the phase validation criteria and record results. -5. After a phase is completed, update `docs/plans/-.md` to reflect completed work and mark phase status. This update is mandatory before moving to the next phase. -6. Create one commit per phase, including code changes and the phase-completion plan update in the same commit. -7. Continue to next phase without pausing only if there are no deviations and no major problems. -8. If any deviation/blocker/major risk appears, pause and report. - -## Parallel execution - -When the plan marks phases as parallelizable, use the Task tool (or any available sub-agent spawning tool) to run them concurrently: - -- **Spawn one sub-agent per independent phase** using `run_in_background: true`. Give each agent a self-contained prompt with all context it needs (file paths, types, contracts, test specifications, validation criteria). -- **Avoid file conflicts**: If two phases write to the same file, combine them into a single agent or sequence them. Different agents should own different files. -- **Shared files** (barrel exports, test config): Let each agent add its own entries. After all agents complete, verify the shared files have no duplicates or conflicts. -- **Wait and verify**: After all parallel agents finish, run a full integration check (compile + full test suite) before committing. This catches cross-agent conflicts in shared files. -- **Single commit for parallel group**: All work from a parallel group goes into one commit after integration verification passes. - -## Required pause report content - -- What was done -- Deviations from plan -- Problems encountered -- Validation results (pass/fail counts and checks run) -- Proposed next step and any decision question for the user - -## Documentation - -- Update `docs/reports` when pausing for deviations/problems. - -## Guardrails - -- If the originating ideation doc is ambiguous, pause and ask the user which ideation file to remove. -- Do not skip plan updates between completed phases. -- Do not switch to review/wrapup implicitly; ask the user to explicitly confirm the next mode. - -## Exit criteria - -- All planned implementation phases are complete and validated, or -- Work is paused with explicit questions for the user. diff --git a/docs/agents/skills/plan/SKILL.md b/docs/agents/skills/plan/SKILL.md deleted file mode 100644 index 57c1bd4..0000000 --- a/docs/agents/skills/plan/SKILL.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -name: plan -description: Convert chosen ideation decisions into a concrete architecture plan focused on selected routes. ---- - -# Instructions - -## Trigger - -Run only when the user explicitly confirms plan mode (for example: converting ideation into a plan or updating the plan). - -## Steps - -1. Create/update `docs/plans/-.md`. This on-disk plan file is mandatory. - - When creating a new plan doc (including ideation -> plan conversion), `` MUST be the next available 3-digit prefix in `docs/plans`. -2. Focus on chosen route(s), not all explored options. -3. **Carry forward all decided features and details from the ideation doc.** Every feature, API surface, design detail, and example that was explored and not explicitly rejected must appear in the plan. No idea can be silently dropped. If unsure whether something was tentatively discussed or firmly decided, ask the user for clarification rather than omitting it. -4. Include: - - Main architecture decisions - - Files expected to change - - Small code examples - - Potential pitfalls - - Remaining unclear areas/decisions - - **Inter-component contracts**: When the architecture has separable parts (layers, modules, packages), make the contracts between them explicit — type definitions, function signatures, shared data structures. These contracts enable parallel implementation in tasks mode. -5. Mention tradeoffs only to explain why chosen paths were selected. -5. Continuously refine the plan with user feedback until it is explicitly approved for implementation. - -## Guardrails - -- Do not add task breakdown in this mode. -- Do not start implementation. -- Do not rely on tool-native planning state alone; all plan content MUST be persisted to `docs/plans/-.md`. -- Do not remove the ideation doc in this mode. - -## Exit criteria - -- Plan clearly reflects chosen decisions. -- Risks and open questions are explicit. -- User has explicitly approved the plan and explicitly confirmed whether to switch to tasks mode or remain in plan mode. diff --git a/docs/agents/skills/review/SKILL.md b/docs/agents/skills/review/SKILL.md deleted file mode 100644 index 8a8ff70..0000000 --- a/docs/agents/skills/review/SKILL.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -name: review -description: Review implemented work against original intent, readiness for external use, remaining gaps, and future completeness work. ---- - -# Instructions - -## Trigger - -Run only when the user explicitly confirms review mode. - -## Review focus - -1. Compare current implementation against the original intent and agreed plan. -2. Assess whether the result is ready for others to use. -3. Identify what is still missing to make this work more complete. -4. Identify gaps or risks in the current implementation. -5. Identify likely future work required for fuller completeness. - -## Output - -Review findings must be emitted in chat first. -Do not write findings to plan or report files until decisions are clarified with the user. - -For each identified gap, ask clarifying questions until both are explicit: - -- whether this gap should be handled now in this session or deferred for future work -- how to approach the gap when multiple implementation routes exist - -After decisions are clear: - -- If handled now: update the active plan file `docs/plans/-.md` with newly added not-yet-completed phases/tasks. -- If deferred: create ideation docs in `docs/ideas`: - - group related deferred items into one ideation doc - - create separate ideation docs only for very different, large deferred tasks - - assign the next available 3-digit prefix in `docs/ideas` for each new ideation doc - -Then report in chat what was updated. -Do not create a separate review report file in this mode. - -## Follow-up questions before switching modes - -**After updating the plan with new phases, always ask the user implementation-specific follow-up questions before offering to switch modes.** New phases added during review are often under-specified because they came from gap analysis rather than upfront design. Proactively ask about: - -- **Placement decisions**: Where should new files/configs live? (e.g. project root vs subfolder) -- **Tool/dependency choices**: Which specific library, image, or tool version to use? -- **Configuration details**: Ports, environment variables, naming conventions -- **Scope boundaries**: How thorough should tests/error messages be? What's worth the maintenance cost vs what's overkill? -- **Anything the agent is unsure about** that would affect the implementation - -Only offer to switch to tasks mode after these questions are answered. This prevents wasted implementation effort from under-specified phases. - - -## Guardrails - -- Do not perform cleanup/release tasks in this mode; use wrapup mode for that. -- Do not remove `docs/plans/-.md` in review mode; plan removal happens in wrapup after report approval. -- If big remaining work is identified, discuss tradeoffs/solutions in chat first. -- Only convert review findings into new not-yet-completed phases/tasks after the user confirms scope and approach. -- After adding new phases/tasks, ask the user to review the updated plan and ask whether to switch to tasks mode to refine them. -- For newly uncovered work, **always switch to tasks mode first** — never directly to implementation. Tasks mode validates that phases have proper validation criteria, dependency graphs, and parallel opportunities before implementation begins. -- If the user's response to review findings involves clarifying approach or scope (e.g. "do X but not Y", "let's use approach A"), treat this as still in the clarification loop — ask follow-up questions for any remaining ambiguity before switching modes. - -## Exit criteria - -- Gaps are clarified with explicit user decisions (now vs future, and chosen approach where needed). -- If now-work exists, plan was updated with new phases/tasks and user was asked whether to switch to tasks mode. -- If future-work exists, ideation docs were created according to grouping rules and user was informed. -- User has explicitly confirmed whether to: - - stay in review mode, - - switch to tasks mode (required path for any new implementation work), - - switch to ideation mode for future work, - - or move to wrapup mode (only when no new implementation work remains). diff --git a/docs/agents/skills/tasks/SKILL.md b/docs/agents/skills/tasks/SKILL.md deleted file mode 100644 index 6caa833..0000000 --- a/docs/agents/skills/tasks/SKILL.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -name: tasks -description: Break an approved plan into ordered phases and concrete tasks with explicit validation criteria. ---- - -# Instructions - -## Trigger - -Run only when the user explicitly confirms tasks mode. - -## Steps - -1. Update the active plan doc in `docs/plans/-.md`. Task breakdown MUST be persisted in this same on-disk plan file. -2. Define implementation phases. -3. Define concrete tasks under each phase. -4. Add explicit validation criteria per phase (for example: unit tests, integration tests, build/typecheck commands, targeted runtime checks). -5. Write detailed test specifications for every phase (see **Test specification** below). -6. Ensure phases are commit-friendly (one commit per phase). - -## Parallel execution - -Phases should be designed for maximum parallelism — different agents may implement different phases or tasks concurrently. - -- **Identify the dependency graph**: Which phases depend on which? Which can run in parallel? Mark this explicitly in the task breakdown. -- **Contracts first**: If the plan defines inter-component contracts (types, interfaces, shared data structures), schedule the contract/types phase first. Once contracts are established, phases that only depend on those contracts can run in parallel. -- **Stub boundaries**: When a phase depends on another phase's output, note what stubs or mocks are needed so it can proceed independently. For example: "Agent B can stub `irToAlgebra()` with hand-crafted algebra objects to test `algebraToString()` independently." -- **Mark parallel groups**: Use explicit notation in the task breakdown to indicate which phases can run simultaneously. For example: "Phase 2a, 2b, 2c can run in parallel after Phase 1." -- **Integration phase last**: After all parallel phases complete, include an explicit integration phase that: (1) replaces stubs with real wiring between components, (2) verifies all parts compile and work together, (3) runs end-to-end / golden tests that exercise the full pipeline. This phase must be planned even when stubs seem trivial — it catches type mismatches, import issues, and cross-component edge cases that unit tests miss. - -## Validation specification - -Every phase must include a **Validation** section that describes the checks an implementing agent must perform and pass before considering the phase complete. Validation is not limited to coded tests — it includes any check that truly proves the work is correct. - -**Types of validation checks** (use whichever are appropriate for the phase): -- **Unit/integration tests**: Coded test files with named test cases and concrete assertions. -- **Compilation/type-check**: e.g. `npm run compile` passes with no errors. -- **Runtime checks**: e.g. "execute the generated SPARQL against a running store and verify results". -- **Manual structural checks**: e.g. "assert the exported function is importable from the barrel", "assert the generated file exists and contains expected content". -- **HTTP/network checks**: e.g. "POST to the endpoint and verify 200 response with expected payload". - -**When describing coded tests:** -- **Name each test case** with the fixture or scenario it covers (e.g. `` `selectName` — `Person.select(p => p.name)` ``). -- **State concrete assertions** — not just "test that it works" but what specifically must be true. Use "assert" language: "assert result is array of length 4", "assert field `name` equals `'Semmy'`", "assert plan type is `'select'`". -- **Include input and expected output** where practical — hand-crafted input objects, specific field values, structural expectations (e.g. "assert algebra contains a LeftJoin wrapping the property triple"). -- **Cover edge cases explicitly** — null handling, missing values, type coercion, empty inputs. -- **Specify test file paths** — e.g. `src/tests/sparql-algebra.test.ts`. - -**When describing non-test validation:** -- **State the exact command or check** to run and what a passing result looks like. -- **Be specific about success criteria** — "compiles" is too vague; "`npx tsc --noEmit` exits 0 with no errors" is clear. - -The validation specifications serve as the phase's acceptance criteria: a phase is only complete when all described checks pass. - -## Guardrails - -- Do not start implementation unless user explicitly requests implementation mode. - -## Exit criteria - -- Every phase has tasks and validation criteria. -- Dependency graph and parallel opportunities are explicit. -- Stubs needed for parallel execution are noted. -- User has explicitly confirmed whether to switch to implementation mode or remain in tasks mode. diff --git a/docs/agents/skills/workflow/SKILL.md b/docs/agents/skills/workflow/SKILL.md deleted file mode 100644 index 086c3f6..0000000 --- a/docs/agents/skills/workflow/SKILL.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -name: workflow -description: Enforce the explicit mode cadence (ideation -> plan -> tasks -> implementation -> review -> wrapup) with transition gates and optional single-mode overrides, and route explicit automatic-mode requests to the automatic meta workflow. ---- - -# Instructions - -## When to use - -- Default for any task that touches code or modifies planning/docs. - -## Mode selection at task start - -- If the user has already explicitly chosen a mode (or explicitly called a mode skill), enter that mode directly. -- `automatic` is a special meta mode and can only be entered when the user explicitly requests it. -- Never auto-suggest `automatic` in startup prompts. -- **Auto-enter ideation**: If the user is clearly brainstorming — weighing trade-offs, thinking out loud, exploring options — enter `ideation` mode directly without asking. This exception applies **only to ideation** (the first mode in the sequence). For all other starting modes (plan, implementation, etc.), always ask first. -- If the user is not clearly ideating, ask using this prompt pattern: - `Should we start with exploring the options in ideation mode? Or do you want to go straight to planning the details in plan mode?` - If the user is already asking to DO specific things, you can also add: `Or should I just go ahead and jump to implementation mode?` -- If the user asks to create/open/update a PR, or asks for PR title/body/message, treat that as an explicit request to enter `wrapup` mode. - -## Mode sequence - -1. `ideation` -2. `plan` -3. `tasks` -4. `implementation` -5. `review` -6. `wrapup` - -Meta mode: - -- `automatic` (explicit-only): run the full workflow without user confirmations between internal mode transitions; handoff behavior is defined in `docs/agents/skills/automatic/SKILL.md`. - -## Transition gates -Only switch to the next sequential mode with explicit user confirmation. When completing any mode, the agent must ask: `Shall we switch to {name of next mode}?`. -Never skip a mode unless explicitly told to. -If user seems to suggest skipping a mode but is not explicitly saying which mode to use, then the agent must ask the user `Do you want to continue with {name of next mode} or continue straight to {user suggested mode}?` -When review identifies remaining work, the agent may loop `review -> tasks -> implementation -> review`, but every switch still requires explicit user confirmation. -When review defers work for future scope, the agent may switch `review -> ideation`, with explicit user confirmation. -Requests related to PR preparation/publishing are an explicit exception and should route directly to `wrapup` mode. -These transition gates apply to standard modes. `automatic` mode is an explicit exception and manages internal transitions autonomously until its review pause point. - -## Required artifacts by mode - -- `ideation`: update/create `docs/ideas/-.md` -- `plan`: update/create `docs/plans/-.md` -- `tasks`: update the same plan doc with phased tasks and validation criteria -- `implementation`: update the plan doc after every completed phase; remove the originating ideation doc once implementation starts -- `review`: emit findings in chat first; after user decisions, update plan with now-work tasks and/or create ideation docs for deferred future work -- `wrapup`: convert plan into a final report doc in `docs/reports`, then remove the plan doc after report approval - -## Global constraints - -- Tool-native plan modes do NOT replace the on-disk plan file requirement. -- After each completed implementation phase, the on-disk plan file MUST be updated before moving to the next phase. -- Mode changes are never implicit; every mode switch requires explicit user confirmation. -- Numbering rule: when creating a new doc in `docs/ideas`, `docs/plans`, or `docs/reports`, `` MUST be the next available 3-digit prefix in the destination folder. -- Conversion rule: when converting/moving docs across folders (for example `ideas -> plans` or `plans -> reports`), do not reuse the old prefix; assign the next available prefix in the destination folder and update references accordingly. diff --git a/docs/agents/skills/wrapup/SKILL.md b/docs/agents/skills/wrapup/SKILL.md deleted file mode 100644 index 66ea2f2..0000000 --- a/docs/agents/skills/wrapup/SKILL.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -name: wrapup -description: Finalize cleanup and release prep by removing dead code, improving comments/docs, running changesets, and drafting PR title/message. ---- - -# Instructions - -## Trigger - -Run only when the user explicitly confirms wrapup mode. -Also treat any user request to prepare/open/update a PR, or draft PR title/body/message, as an explicit wrapup request. - -## Steps - -1. Update `docs/plans/-.md` by appending a `## REVIEW` section at the end with wrapup outcomes and PR-readiness status. -2. Convert `docs/plans/-.md` into a report doc in `docs/reports/-.md`. - - For this conversion, the report `` MUST be the next available 3-digit prefix in `docs/reports` (do not reuse the plan prefix when it conflicts). - - Update any references to the report path after conversion. -3. **Report quality** — see the dedicated section below. The report is a condensed but comprehensive record of everything that was done. It is NOT a brief summary. -4. Consolidate remaining tradeoffs/choices into final decisions made and rationale. -5. Remove dead code related to the implemented scope. -6. Add clarifying comments in changed code where needed. -7. Verify documentation coverage for what changed. -8. Run a PR-readiness checklist and identify anything missing (for example: docs updates, tests/validation evidence, plan/report consistency, release notes). -9. If anything is missing, notify the user with a concrete checklist and ask whether to add/fix the missing items now. -10. Changeset handling — see the dedicated section below. -11. Draft a PR title and PR message/body summarizing changes, validation, and follow-up notes. -12. After the report is reviewed and approved by the user, remove `docs/plans/-.md`. - -## Report quality - -The report replaces the plan as the permanent record. Any agent working on code that interacts with the changed code must be able to understand from this document what was built, how it works, and what decisions were made. The report should be proportional to the scope of the plan — a large plan produces a substantial report. - -**What to keep from the plan (condense but do NOT drop):** -- Architecture overview and pipeline description -- All key design decisions with rationale (e.g., why OPTIONAL wrapping, why VariableRegistry, why DELETE/INSERT/WHERE over DELETE WHERE) -- File structure with each file's responsibility -- Public API surface (exported functions, classes, types) with usage examples -- Conversion/mapping rules (e.g., IR node → algebra node mapping tables) -- All resolved gaps, bugs, and edge cases with their chosen approach -- Test coverage summary (which test files, what they cover, total counts) -- Known limitations and remaining test gaps -- Deferred work with pointers to ideation docs -- Links to relevant documentation files (e.g., `documentation/sparql-algebra.md`) -- PR reference (number and URL) when a PR was created during this scope -- Anything that affects future work or that future agents need to know - -**What to remove from the plan:** -- Alternative approaches that were NOT chosen (unless the rationale for rejection informs future decisions) -- Per-phase task checklists and status markers (the work is done) -- Detailed per-test assertions (keep test file names and what they cover, drop individual assertion lists) -- Inline code snippets that duplicate what's in the actual source files (keep small illustrative examples) -- Validation command logs - -**Sizing guideline:** If the plan was 500+ lines, the report should be at least 150-300 lines. A 10-line report for a 3000-line plan means critical information was lost. - -## Changeset handling - -**Always create a changeset** when package code changed, even if other changesets already exist. Each changeset becomes a separate entry in the public changelog via CI/CD, so it should describe what users of the library need to know about THIS set of changes. - -A changeset is only skippable when the scope is purely internal (docs, CI config, dev tooling) with zero impact on the published package. - -**Changeset content must be user-facing and actionable:** -- List new exports, classes, functions, and types that users can now import -- Describe new capabilities and how to use them (brief code examples) -- Note any breaking changes or behavioral differences -- Reference documentation files where users can learn more -- Do NOT write vague summaries like "added SPARQL support" — be specific about what was added and how to use it - -**Process:** -- Ask the user for the version bump level (patch/minor/major) unless they already specified it. -- The `npx @changesets/cli add` command requires interactive TTY input, which is not available in agent environments. Instead, write the changeset file directly to `.changeset/` — this is the standard approach for CI/automation and produces identical results. Use the standard format: YAML frontmatter with package name and bump level, followed by markdown description. Use a descriptive kebab-case filename (e.g., `sparql-conversion-layer.md`). - -## Output - -- Updated `docs/plans/-.md` with `## REVIEW` section at end. -- Final report at `docs/reports/-.md`. -- Changeset file in `.changeset/` (when applicable). - -## Exit criteria - -- Cleanup and documentation checks are complete. -- PR readiness gaps (if any) were surfaced to the user and a decision was collected. -- Changeset requirement is resolved (prepared, or explicitly skipped for docs-only/no-code-change scope). -- PR title and message are ready. -- Final report is approved and the corresponding plan doc has been removed. diff --git a/package.json b/package.json index d27e9bf..e9b65e3 100644 --- a/package.json +++ b/package.json @@ -42,8 +42,8 @@ "build": "npx rimraf ./lib && npx tsc -p tsconfig-cjs.json && npx tsc -p tsconfig-esm.json && node ./scripts/dual-package.js", "compile": "echo '💫 Compiling CJS' && npx tsc -p tsconfig-cjs.json && echo '💫 Compiling ESM' && npx tsc -p tsconfig-esm.json", "dual-package": "node ./scripts/dual-package.js", - "sync:agents": "node ./scripts/sync-agents.mjs", - "setup": "npm run sync:agents", + "sync:agents": "node packages/skills/sync.mjs", + "setup": "node scripts/setup.mjs", "test": "npx jest --config jest.config.js", "test:fuseki": "docker compose -f src/tests/docker-compose.test.yml up -d --wait && npx jest --config jest.config.js --testPathPattern='sparql-fuseki' --verbose; EXIT=$?; docker compose -f src/tests/docker-compose.test.yml down; exit $EXIT" }, diff --git a/scripts/setup.mjs b/scripts/setup.mjs new file mode 100644 index 0000000..2baf33d --- /dev/null +++ b/scripts/setup.mjs @@ -0,0 +1,33 @@ +#!/usr/bin/env node + +import {execSync} from 'node:child_process'; +import {existsSync} from 'node:fs'; +import path from 'node:path'; + +const projectRoot = process.cwd(); +const skillsDir = path.join(projectRoot, 'packages', 'skills'); +const skillsRepo = 'git@github.com:Semantu/agents.git'; + +function run(cmd, opts) { + return execSync(cmd, {stdio: 'inherit', ...opts}); +} + +function setupSkills() { + if (existsSync(path.join(skillsDir, '.git'))) { + console.log('Updating skills repo...'); + run('git pull --ff-only', {cwd: skillsDir}); + } else { + console.log('Cloning skills repo...'); + run(`git clone ${skillsRepo} ${skillsDir}`); + } + + console.log('Syncing skills...'); + run('node sync.mjs', {cwd: skillsDir}); +} + +try { + setupSkills(); +} catch { + console.log('\nSkipping skills setup — could not access the skills repo.'); + console.log('This is fine if you don\'t have access to github.com:Semantu/agents.'); +} diff --git a/scripts/sync-agents.mjs b/scripts/sync-agents.mjs deleted file mode 100644 index 828d05e..0000000 --- a/scripts/sync-agents.mjs +++ /dev/null @@ -1,22 +0,0 @@ -import {cpSync, existsSync, mkdirSync, rmSync} from 'node:fs'; -import path from 'node:path'; - -const projectRoot = process.cwd(); -const sourceDir = path.join(projectRoot, 'docs', 'agents'); -const skillsSourceDir = path.join(sourceDir, 'skills'); -const targets = [ - {source: skillsSourceDir, dest: path.join(projectRoot, '.claude', 'skills')}, - {source: skillsSourceDir, dest: path.join(projectRoot, '.agents', 'skills')}, -]; - -if (!existsSync(sourceDir)) { - console.error(`Source directory not found: ${sourceDir}`); - process.exit(1); -} - -for (const {source, dest} of targets) { - rmSync(dest, {recursive: true, force: true}); - mkdirSync(path.dirname(dest), {recursive: true}); - cpSync(source, dest, {recursive: true}); - console.log(`Synced ${source} -> ${dest}`); -}