thomas-agentkit 0.7.0 → 0.9.0-alpha.0

package/templates/skills/agentkit/references/file-contract.md

@@ -0,0 +1,163 @@
+# AgentKit File Contract
+
+Read this before creating, updating, auditing, or repairing any AgentKit-managed guidance file.
+
+This contract is the shared rulebook for AgentKit guidance-edit workflows. Route files define procedure; this file defines the invariants every route must preserve.
+
+## Config
+
+Read `agentkit.config.json` from the repository root when present:
+
+| Field | Use |
+| --- | --- |
+| `installMode` | `"skill"` confirms a skill-path project; missing values are treated as template-path unless the user explicitly invokes the skill workflow |
+| `agentkitVersion` | Package version at skill install; informational |
+| `templateSet` | `minimal`, `standard`, or `full`; determines configured guidance inventory |
+| `preset` | Stack preset (`next`, `sveltekit`, `express`, `convex`, `fullstack`) used for `STACK.md` |
+| `aiTools` | Which thin adapter files to create (`codex`, `cursor`, `claude`, `copilot`) |
+| `designSystem` | `linear` or `apple`; style lens for `DESIGN-SYSTEM.md` |
+| `personalization` | Fallback defaults for project name, commands, and paths; repo facts win when available |
+
+Prefer repository facts over config personalization. Use config values as defaults, not as a reason to ignore visible codebase reality.
+
+## Route Behavior
+
+- `agentkit init`: create missing configured guidance files from repo context; skip existing files by default.
+- `agentkit update`: refresh valid AgentKit managed blocks and create missing configured files; skip unmanaged files by default.
+- `agentkit doctor`: audit guidance quality and report findings; do not edit by default.
+- `agentkit learn`: teach recent codebase changes; do not edit or create files by default.
+- Refresh, conversion, repair, or wholesale regeneration requires an explicit user request.
+
+## File Inventory
+
+### Template sets
+
+`minimal`:
+
+- `AGENTS.md`
+
+`standard`:
+
+- `AGENTS.md`
+- `CHANGE-EXPLANATION.md`
+- `CODE-QUALITY.md`
+- `DESIGN-SYSTEM.md`
+- `.github/pull_request_template.md`
+
+`full`:
+
+- Everything in `standard`
+- `TESTING.md`
+- `SECURITY-CHECKLIST.md`
+- `WORKFLOWS.md`
+- `PRD-TEMPLATE.md`
+- `IMPLEMENTATION-BRIEF-TEMPLATE.md`
+
+### AI tool adapters
+
+Adapters are additive and controlled by `aiTools` or explicit user request. Do not create adapters for unselected tools just because `templateSet` is `full`.
+
+| Tool | File |
+| --- | --- |
+| `codex` | Uses `AGENTS.md` directly; no adapter file |
+| `cursor` | `.cursor/rules/agentkit.md` |
+| `claude` | `CLAUDE.md` |
+| `copilot` | `.github/copilot-instructions.md` |
+
+Adapters are thin pointers to `AGENTS.md`. Do not duplicate operating rules.
+
+### Stack guidance
+
+Create or update `STACK.md` when:
+
+- `preset` is set in config
+- the user explicitly asks for stack guidance
+- stack signals are strong enough to infer a preset confidently
+
+When `STACK.md` exists or will be created, `AGENTS.md` should tell agents to read `STACK.md` before stack-specific changes.
+
+## File Roles
+
+- `AGENTS.md`: source-of-truth router; project purpose, project map, real commands, workflow expectations, companion-doc routing, safety rules, and before-finishing checklist.
+- `STACK.md`: stack-specific guidance based on repo facts and configured or inferred preset.
+- `CHANGE-EXPLANATION.md`: handoff, summary, and change-explanation expectations.
+- `CODE-QUALITY.md`: review, refactor, and maintainability guidance; reference commands from `AGENTS.md`.
+- `DESIGN-SYSTEM.md`: UI/design guidance for detected or configured UI surfaces.
+- `.github/pull_request_template.md`: concise PR checklist; do not over-personalize per-work-item templates.
+- `TESTING.md`: detected test tools, test locations, and real test commands.
+- `SECURITY-CHECKLIST.md`: project-relevant security boundaries such as auth, secrets, API inputs, and data access.
+- `WORKFLOWS.md`: repo-specific planning, review, release, and development workflows.
+- `PRD-TEMPLATE.md`: reusable product requirements template; do not fill with current work.
+- `IMPLEMENTATION-BRIEF-TEMPLATE.md`: reusable implementation planning template; do not fill with current work.
+- AI adapters: thin pointers to `AGENTS.md`.
+
+## Managed Blocks
+
+AgentKit-owned content must be wrapped in paired markers:
+
+```html
+<!-- agentkit:start <id> -->
+Generated content
+<!-- agentkit:end <id> -->
+```
+
+Rules:
+
+- Use stable ids, such as `agents`, `stack`, `design-system`, `testing`, or `security-checklist`.
+- For new files, usually wrap the full AgentKit-generated body in one top-level managed block.
+- Adapters can be fully managed because they should only point to `AGENTS.md`.
+- Preserve all user edits before and after managed blocks.
+- Replace only valid managed block content during update or refresh.
+- Skip unmanaged existing files unless the user explicitly asks to convert them.
+- Malformed managed block markers block edits to that file; defer and recommend repair.
+
+## Repository Inspection
+
+Inspect before writing or auditing:
+
+1. `package.json` for name, description, and scripts
+2. Lockfiles for package manager
+3. Framework signals, such as `next.config.*`, `svelte.config.*`, `convex/`, `vite.config.*`, `app/`, or `pages/`
+4. Source layout, such as `src/`, `test/`, `tests/`, `docs/`, `.github/`
+5. Test runner and tooling config, such as Vitest, Jest, Playwright, ESLint, TypeScript, or build config
+6. UI/design signals, such as Tailwind config, CSS files, component folders, or design docs
+7. Backend/data/auth signals, such as API routes, schema files, auth packages, or server modules
+8. Existing guidance files and managed block markers
+
+Prefer repo facts over config personalization when they conflict.
+
+## Placeholder And Command Rules
+
+Replace bracket placeholders with real values from the repo or omit the placeholder-dependent section:
+
+| Placeholder | Source |
+| --- | --- |
+| `[Project Name]` | `package.json` name or directory name |
+| `[short project description]` | `package.json` description or README first paragraph |
+| `[issue tracker, e.g. Linear or GitHub Issues]` | `personalization.issueTracker` or infer from `.github/` |
+| `[design system path, e.g. docs/design-system.md]` | `personalization.designSystemPath`, existing design docs, or `DESIGN-SYSTEM.md` |
+| `[briefs path, e.g. docs/briefs]` | `personalization.briefsPath`, existing docs path, or omit |
+| Project commands | Real scripts from `package.json` or explicit user/config personalization |
+
+Never invent scripts. If a command is not present and not explicitly provided, omit it or describe that it is not configured.
+
+## Healthy Guidance Criteria
+
+AgentKit guidance is healthy when:
+
+- Required files for the configured inventory exist or are intentionally deferred.
+- `AGENTS.md` is present and acts as the router/source of truth.
+- Managed block markers are paired and stable.
+- Commands match `package.json` scripts or explicit user/config personalization.
+- No `[Project Name]`-style placeholders remain in AgentKit-managed content.
+- `AGENTS.md` references only companion files that exist or are being created.
+- `STACK.md` exists when configured or confidently inferred, and `AGENTS.md` references it.
+- AI adapters point to `AGENTS.md` and do not duplicate full operating rules.
+- Generated guidance reflects visible repo facts instead of generic filler.
+
+## Edit Boundaries
+
+- Do not modify application source code, lockfiles, package manifests, or CI config during AgentKit workflows.
+- Do not delete user-written content outside managed blocks.
+- Do not run `git commit`, `git push`, or destructive shell commands.
+- Docs-only and learn workflows do not require running project test/build commands.

package/templates/skills/agentkit/references/init.md

@@ -0,0 +1,212 @@
+# agentkit init (skill workflow)
+
+Create AgentKit guidance files from the current repository context. This workflow runs **inside the agent** after `agentkit skill install`; it is not the CLI `agentkit init` template installer.
+
+The skill path is context-aware. Do not copy generic templates when repository facts are available. Use AgentKit's file contract as structure, then author guidance from the codebase in front of you.
+
+## Preconditions
+
+- Read `references/file-contract.md` before editing any AgentKit-managed file.
+- Prefer `agentkit.config.json` when present.
+- If config is missing but the user explicitly requested `/agentkit init`, continue with safe defaults:
+  - `templateSet: standard`
+  - `aiTools: ["codex"]`
+  - infer `preset` from repository signals when obvious
+  - infer `designSystem` only when UI/design signals exist
+
+## Non-negotiables
+
+- Create missing guidance files only by default.
+- Skip existing files unless the user explicitly asks to refresh or regenerate them.
+- Preserve user content outside AgentKit managed blocks.
+- Never invent commands. Commands must come from `package.json` scripts or explicit user/config personalization.
+- Replace all bracket placeholders with real values or omit the placeholder-dependent section.
+- Do not modify application source files, lockfiles, or CI config during init.
+- Keep `AGENTS.md` as the source-of-truth router; adapters stay thin pointers.
+
+## Procedure
+
+### 1. Build Repo Profile
+
+Inspect the repository before choosing file content.
+
+Collect:
+
+- Project name and description from `package.json`, README, or directory name
+- Package manager from lockfiles
+- Scripts from `package.json`
+- Framework/runtime signals, such as Next.js, SvelteKit, Express, Convex, Vite, React, Node, TypeScript
+- Source layout, such as `src/`, `app/`, `pages/`, `convex/`, `test/`, `docs/`
+- Test, lint, build, typecheck, and dev tooling
+- UI/design system signals, such as Tailwind, CSS files, component folders, design docs
+- Backend/data/auth signals, such as API routes, database/schema files, auth packages
+- Existing docs, briefs, PR templates, workflow docs, or agent guidance files
+- Issue tracker/workflow hints from `.github/`, Linear docs, or config personalization
+
+Prefer repository facts over config personalization. Use config personalization only as fallback.
+
+### 2. Resolve AgentKit Config
+
+Read `agentkit.config.json` when present.
+
+Use:
+
+- `installMode`
+- `agentkitVersion`
+- `templateSet`
+- `preset`
+- `aiTools`
+- `designSystem`
+- `personalization`
+
+If values are missing:
+
+- Default `templateSet` to `standard`
+- Default `aiTools` to `["codex"]`
+- Infer `preset` only when repo signals are strong
+- Use `designSystem` only for standard/full installs or when UI guidance is clearly useful
+
+Configs without `installMode` are treated as template-path installs, but if the user explicitly invoked this skill workflow, continue carefully and report the assumption.
+
+### 3. Decide File Inventory
+
+Use `references/file-contract.md` as the source of truth.
+
+Inventory rules:
+
+- `minimal`
+  - `AGENTS.md`
+
+- `standard`
+  - `AGENTS.md`
+  - `CHANGE-EXPLANATION.md`
+  - `CODE-QUALITY.md`
+  - `DESIGN-SYSTEM.md`
+  - `.github/pull_request_template.md`
+
+- `full`
+  - everything in `standard`
+  - `TESTING.md`
+  - `SECURITY-CHECKLIST.md`
+  - `WORKFLOWS.md`
+  - `PRD-TEMPLATE.md`
+  - `IMPLEMENTATION-BRIEF-TEMPLATE.md`
+  - selected AI tool adapters
+
+- `preset` set or confidently inferred
+  - add `STACK.md`
+
+- `aiTools`
+  - `codex`: no adapter; uses `AGENTS.md`
+  - `cursor`: `.cursor/rules/agentkit.md`
+  - `claude`: `CLAUDE.md`
+  - `copilot`: `.github/copilot-instructions.md`
+
+Before writing, briefly tell the user which missing files will be created and which existing files will be skipped.
+
+### 4. Author Missing Files
+
+Create only files that do not already exist.
+
+For each created file:
+
+- Create parent directories if needed.
+- Wrap AgentKit-owned content in managed block markers from `references/file-contract.md`.
+- Use project-specific facts from the repo profile.
+- Avoid generic filler.
+- Keep guidance concise and operational.
+
+File roles:
+
+- `AGENTS.md`
+  - Primary router and source of truth
+  - Include project purpose, project map, real commands, workflow expectations, companion-doc routing, safety rules, and before-finishing checklist
+  - Reference `STACK.md` when created
+  - Reference companion files only when they exist or are part of this init
+
+- `STACK.md`
+  - Stack-specific guidance based on repo facts and configured/inferred preset
+  - Include framework boundaries, source layout, validation points, and relevant checks
+  - Do not include generic framework advice that does not apply to the repo
+
+- `CHANGE-EXPLANATION.md`
+  - Handoff and change-summary expectations
+  - Keep tied to this project's likely workflows and changed-file surfaces
+
+- `CODE-QUALITY.md`
+  - Review, refactor, and maintainability guidance
+  - Reference real project commands from `AGENTS.md`
+  - Avoid duplicating large command tables
+
+- `DESIGN-SYSTEM.md`
+  - Only include design guidance appropriate to the detected UI surface
+  - Use configured `designSystem` as a style lens
+  - Mention real component/style paths when visible
+
+- `.github/pull_request_template.md`
+  - Keep concise and generally useful
+  - Do not over-personalize per-work-item templates
+
+- `TESTING.md`
+  - Include detected test tools and where tests live
+  - Include real test commands only
+
+- `SECURITY-CHECKLIST.md`
+  - Include project-relevant security boundaries such as auth, secrets, API inputs, and data access
+  - Avoid irrelevant compliance boilerplate
+
+- `WORKFLOWS.md`
+  - Capture repo-specific development workflows, planning docs, release steps, or review flow when visible
+
+- `PRD-TEMPLATE.md` and `IMPLEMENTATION-BRIEF-TEMPLATE.md`
+  - Keep as reusable work-item templates
+  - Do not fill them with current project facts beyond light path references
+
+- AI adapters
+  - Keep thin
+  - Point to `AGENTS.md`
+  - Do not duplicate operating rules
+
+### 5. Existing Files And Refresh Requests
+
+Default behavior:
+
+- Skip existing guidance files.
+- Report them as skipped.
+- Do not edit managed blocks during normal init.
+
+If the user explicitly asks to refresh or regenerate existing files:
+
+- Preserve all content outside managed blocks.
+- Replace only AgentKit managed blocks.
+- Stop and recommend `agentkit doctor` or `agentkit repair` if managed block markers are malformed.
+- Never overwrite unmanaged user-written files wholesale unless the user explicitly confirms the exact file.
+
+### 6. Verify
+
+Before finishing, check:
+
+- Every planned missing file was created or explicitly deferred with a reason.
+- Existing files were not overwritten by default.
+- Managed block markers are paired and use stable ids.
+- No `[Project Name]`-style placeholders remain.
+- Commands in guidance match `package.json` scripts or explicit config/user personalization.
+- `AGENTS.md` references `STACK.md` only when `STACK.md` exists.
+- AI adapters point to `AGENTS.md` and do not duplicate full guidance.
+- No application source files, lockfiles, or CI files were modified.
+
+Docs-only init does not require running the project's test/build commands.
+
+### 7. Report
+
+Tell the user:
+
+- Files created
+- Files skipped because they already existed
+- Stack and package manager inferred
+- Commands inferred
+- Config values used
+- Assumptions made
+- Any deferred files and why
+
+Keep the report concise.

package/templates/skills/agentkit/references/learn.md

@@ -0,0 +1,149 @@
+# agentkit learn (skill workflow)
+
+Teach the user what changed in the codebase and help them build durable understanding after an implementation, bug fix, refactor, or agent session.
+
+This workflow is read-only by default. Do not create Markdown notes, edit guidance files, or modify repo state unless the user explicitly asks.
+
+## Preconditions
+
+- Inspect the change context before explaining.
+- Prefer current repo facts, diffs, changed files, and test output over memory of the session.
+- If there are no visible changes, ask which change, branch, commit, or files the user wants to learn.
+- Do not run mutating commands, formatters, code generators, or file writes during learn.
+
+## Non-negotiables
+
+- Teach incrementally; do not dump the whole explanation at once.
+- Start by asking the user to restate their current understanding.
+- Explain the problem before the solution.
+- Cover why, what, and how: motivation, root cause, design choices, business logic, edge cases, validation, and impact.
+- Use real code references and short snippets when useful.
+- Keep the running learning checklist in the conversation, not in a file, unless the user explicitly asks for notes.
+- Check understanding before moving to the next stage, but let the user skip ahead if they ask.
+
+## Procedure
+
+### 1. Build Change Context
+
+Inspect the repository enough to teach accurately.
+
+Use available context such as:
+
+- `git status --short`
+- `git diff --stat`
+- `git diff`
+- changed files relevant to the user's question
+- recent commits only when the user asks about committed work or no working-tree diff exists
+- test, build, or check output when relevant
+
+Identify:
+
+- What changed
+- What problem the change addressed
+- Why the problem existed
+- What branches, cases, or constraints mattered
+- What solution was chosen
+- What tradeoffs were accepted
+- What edge cases or risks remain
+- What tests or checks validate the change
+- What broader behavior, workflow, or maintenance impact exists
+
+### 2. Start With The User's Current Understanding
+
+Before teaching, ask a short calibration question:
+
+```md
+Before I explain, tell me your current read: what problem do you think we solved, and what changed?
+```
+
+Use the answer to fill gaps instead of repeating what the user already understands.
+
+If the user asks for a specific level, adapt to it:
+
+- `ELI5`: plain language and analogies, minimal code
+- `ELI14`: plain language plus simple technical terms
+- `intern`: practical engineering detail, with code walkthroughs
+- `engineer`: concise, precise, tradeoff-aware
+- `expert`: focus on invariants, edge cases, and design alternatives
+
+### 3. Teach In Stages
+
+Use this order:
+
+1. Problem
+   - What was wrong or missing
+   - Why it mattered
+   - Why it existed
+   - What branches or cases were involved
+
+2. Solution
+   - What changed
+   - Why this approach was chosen
+   - What alternatives were avoided
+   - What behavior is now explicit
+
+3. Code walkthrough
+   - Important files and functions
+   - How data or control flows through the changed code
+   - Business logic and edge cases
+   - Short snippets or file references where helpful
+
+4. Validation and impact
+   - Tests or checks that support the change
+   - What users or developers will notice
+   - What remains unchanged
+   - What follow-up work or risks remain
+
+After each stage, ask the user to restate the key idea or answer a small check question before continuing.
+
+### 4. Maintain A Conversation Checklist
+
+Keep a visible checklist in the conversation:
+
+```md
+Learning checklist
+
+- [ ] The original problem and why it existed
+- [ ] The main solution and why this design was chosen
+- [ ] The changed files and how code flows through them
+- [ ] The business logic and edge cases
+- [ ] The tests or checks that validate the behavior
+- [ ] The broader impact and maintenance implications
+```
+
+Mark items as understood only after the user demonstrates understanding or asks to move on.
+
+### 5. Use Code Well
+
+When discussing code:
+
+- Cite real files and line numbers when possible.
+- Prefer short snippets over large pasted sections.
+- Show before/after comparisons when they clarify the change.
+- Trace one important value, branch, or request through the code when useful.
+- Avoid overwhelming the user with every changed line.
+
+### 6. Mastery Checks
+
+Use lightweight checks such as:
+
+- "Can you explain why this bug happened in your own words?"
+- "What would break if we removed this branch?"
+- "Which file would you inspect first if this regressed?"
+- "What edge case is this guard protecting?"
+- "Why did this solution fit better than the simpler alternative?"
+
+If the user struggles, explain again at a simpler level and ask a narrower question.
+
+### 7. Final Recap
+
+End with a concise recap:
+
+- What changed
+- Why it changed
+- How it works
+- What validates it
+- What to watch for
+- What the user now understands
+
+Do not create files unless explicitly requested.

package/templates/skills/agentkit/references/repair.md

@@ -0,0 +1,119 @@
+# agentkit repair (skill workflow)
+
+Repair AgentKit guidance structure after an explicit user request. This workflow fixes guidance-file safety problems that block `agentkit update`, especially malformed managed blocks, unmanaged-file conversion, broken adapters, stale companion references, and missing managed wrappers.
+
+Repair is not a general rewrite workflow. Use `agentkit update` for stale content and `agentkit doctor` for read-only audits.
+
+## Preconditions
+
+- Read `references/file-contract.md` before repairing any file.
+- Read `agentkit.config.json` when present.
+- Inspect the affected guidance files before proposing repairs.
+- Briefly tell the user which files need repair and what will change before editing.
+
+## Non-negotiables
+
+- Preserve user-written content.
+- Modify only AgentKit guidance files and AI tool adapters.
+- Do not modify application source files, lockfiles, package manifests, or CI config.
+- Do not guess ownership when managed block markers are ambiguous.
+- Do not regenerate whole files unless the user explicitly asks for that exact file.
+- Keep `AGENTS.md` as the source of truth; adapters stay thin pointers.
+
+## Procedure
+
+### 1. Identify Repair Targets
+
+Inspect:
+
+- `AGENTS.md`
+- `STACK.md`
+- companion guidance files
+- AI tool adapters
+- managed block markers
+- companion references in `AGENTS.md`
+
+Classify each target:
+
+- Malformed managed block markers
+- Missing managed wrapper around AgentKit-owned content
+- Unmanaged guidance file the user wants converted
+- AI adapter that duplicates full guidance or points to the wrong source
+- `AGENTS.md` references to missing companion files
+- Configured guidance file missing a safe managed block
+
+### 2. Plan The Repair
+
+Before editing, report:
+
+- Files to repair
+- Repair type for each file
+- Files deferred because ownership is ambiguous
+- Any user confirmation needed
+
+If ownership is ambiguous, defer the file and ask the user whether to convert, preserve, or leave it unmanaged.
+
+### 3. Repair Managed Blocks
+
+For malformed markers:
+
+- Repair obvious one-start/one-end pairing issues only when the intended block boundaries are clear.
+- Preserve all text outside the repaired block.
+- Keep the same stable block id when clear.
+- If there are multiple starts, multiple ends, overlapping blocks, or unclear ownership, defer instead of guessing.
+
+For missing wrappers:
+
+- Add one top-level AgentKit managed block around clearly AgentKit-owned generated content.
+- Preserve pre-existing user notes outside the managed block when possible.
+- Do not wrap unrelated project documentation.
+
+### 4. Convert Unmanaged Files
+
+Only convert an unmanaged file when the user explicitly asks.
+
+When converting:
+
+- Preserve existing user-written content outside the new managed block when possible.
+- Add one AgentKit managed block for generated AgentKit guidance.
+- Do not delete custom instructions.
+- Do not convert application docs that are not part of AgentKit guidance.
+
+### 5. Repair AI Adapters
+
+For `.cursor/rules/agentkit.md`, `CLAUDE.md`, and `.github/copilot-instructions.md`:
+
+- Replace thick duplicated guidance with a thin pointer to `AGENTS.md`.
+- Wrap the adapter body in a managed block.
+- Preserve any user-specific adapter notes outside the managed block when present.
+
+### 6. Repair Companion References
+
+For `AGENTS.md` companion references:
+
+- Remove references to companion files that do not exist and are not being created.
+- Add references to existing configured companions when useful.
+- Reference `STACK.md` only when it exists or will be created.
+
+### 7. Verify
+
+Before finishing, check:
+
+- Managed block markers are paired and stable.
+- User-written content outside managed blocks was preserved.
+- AI adapters point to `AGENTS.md` and do not duplicate full guidance.
+- `AGENTS.md` references only companion files that exist.
+- No application source files, lockfiles, package manifests, or CI files were modified.
+
+Docs-only repair does not require running the project's test/build commands.
+
+### 8. Report
+
+Tell the user:
+
+- Files repaired
+- Files deferred and why
+- Repairs performed
+- Any follow-up recommendation, such as `/agentkit update` after structural repair
+
+Keep the report concise.