thomas-agentkit 0.8.0 → 0.9.0-alpha.1

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.

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

@@ -0,0 +1,202 @@
+# agentkit update (skill workflow)
+
+Sync existing AgentKit guidance files with the current repository context. This workflow runs **inside the agent** for skill-path projects; it is not the CLI `agentkit update` managed-block template merger.
+
+The skill path is context-aware. Re-read the repository, compare guidance against current codebase reality, and update only AgentKit-managed content.
+
+## Preconditions
+
+- Read `references/file-contract.md` before editing any AgentKit-managed file.
+- Read `agentkit.config.json` when present.
+- If `installMode: skill`, continue with this workflow.
+- If `installMode: template` or config is missing, continue only when the user explicitly asked for the skill workflow; otherwise direct them to CLI `agentkit update`.
+
+## Non-negotiables
+
+- Preserve user content outside AgentKit managed blocks.
+- Never invent commands. Commands must come from `package.json` scripts or explicit user/config personalization.
+- Do not overwrite unmanaged existing files.
+- Stop on malformed managed block markers and recommend `agentkit repair` before updating that file.
+- Do not modify application source files, lockfiles, package manifests, or CI config during update.
+- Keep `AGENTS.md` as the source-of-truth router; adapters stay thin pointers.
+
+## Procedure
+
+### 1. Build Fresh Repo Profile
+
+Inspect the repository again before deciding what to update.
+
+Collect:
+
+- Project name and description from `package.json`, README, or directory name
+- Package manager from lockfiles
+- Current scripts from `package.json`
+- Framework/runtime signals, such as Next.js, SvelteKit, Express, Convex, Vite, React, Node, TypeScript
+- Current source layout, such as `src/`, `app/`, `pages/`, `convex/`, `test/`, `docs/`
+- Current 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. Read Current AgentKit State
+
+Inspect:
+
+- `agentkit.config.json`
+- `AGENTS.md`
+- `STACK.md`
+- companion guidance files
+- AI tool adapters
+- managed block markers in every AgentKit guidance file
+
+Record:
+
+- Files present
+- Files missing for the configured `templateSet`, `preset`, and `aiTools`
+- Files with managed blocks
+- Files without managed blocks
+- Files with malformed managed blocks
+
+### 3. Decide Sync Scope
+
+Use `references/file-contract.md` as the source of truth for inventory.
+
+Update should handle:
+
+- Stale commands
+- Stale project name or description
+- Stale stack/framework guidance
+- Changed source layout
+- Changed test/build/lint tooling
+- Changed design system or docs paths
+- Missing companion files implied by `templateSet`
+- Missing `STACK.md` when `preset` is set or stack is confidently inferred
+- Missing AI adapters implied by `aiTools`
+- Adapters that duplicate operating rules instead of pointing to `AGENTS.md`
+- Remaining bracket placeholders
+
+Before writing, briefly tell the user which files will be updated, created, skipped, or deferred.
+
+### 4. Update Managed Files
+
+For each existing AgentKit guidance file:
+
+- If the file has a valid AgentKit managed block, replace only the managed block content.
+- Preserve all text before and after the managed block exactly.
+- If the file exists but has no managed block, skip it unless the user explicitly asks to convert it.
+- If the file has malformed managed blocks, defer it and recommend `agentkit repair`.
+- Use current repo facts from the fresh repo profile.
+- Avoid generic filler.
+- Keep guidance concise and operational.
+
+File roles:
+
+- `AGENTS.md`
+  - Refresh project purpose, project map, real commands, workflow expectations, companion-doc routing, safety rules, and before-finishing checklist
+  - Reference only companion files that exist or will be created in this update
+  - Reference `STACK.md` only when it exists or will be created
+
+- `STACK.md`
+  - Refresh stack-specific guidance based on current repo facts and configured/inferred preset
+  - Include current framework boundaries, source layout, validation points, and relevant checks
+  - Remove or avoid generic framework advice that does not apply to the repo
+
+- `CHANGE-EXPLANATION.md`
+  - Refresh handoff and change-summary expectations when project workflow signals changed
+
+- `CODE-QUALITY.md`
+  - Refresh review, refactor, and maintainability guidance
+  - Reference real project commands from `AGENTS.md`
+  - Avoid duplicating large command tables
+
+- `DESIGN.md`
+  - Refresh UI design spec only when a UI/design surface exists or the file is configured
+  - Use configured `designSystem` baseline; map tokens to project theme
+  - Mention current component/style paths when visible
+  - Prefer `/agentkit design` when user wants baseline selection or customization
+
+- `.github/pull_request_template.md`
+  - Keep concise and generally useful
+  - Do not over-personalize per-work-item templates
+
+- `TESTING.md`
+  - Refresh detected test tools, test locations, and real test commands
+
+- `SECURITY-CHECKLIST.md`
+  - Refresh project-relevant security boundaries such as auth, secrets, API inputs, and data access
+  - Avoid irrelevant compliance boilerplate
+
+- `WORKFLOWS.md`
+  - Refresh 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
+  - Avoid filling them with current project facts beyond light path references
+
+- AI adapters
+  - Keep thin
+  - Point to `AGENTS.md`
+  - Do not duplicate operating rules
+
+### 5. Create Missing Configured Files
+
+Create missing files implied by `templateSet`, `preset`, or `aiTools`.
+
+For each created file:
+
+- Create parent directories if needed.
+- Wrap AgentKit-owned content in managed block markers from `references/file-contract.md`.
+- Use current repo facts from the fresh repo profile.
+- Report the file as created.
+
+Do not create unrelated guidance files outside the configured inventory unless the user asks.
+
+### 6. Handle Unmanaged Or Malformed Files
+
+Default behavior:
+
+- Skip unmanaged existing files.
+- Defer malformed files.
+- Report why each file was skipped or deferred.
+
+If the user explicitly asks to convert an unmanaged file:
+
+- Preserve the original content outside the new managed block when possible.
+- Add one AgentKit managed block for generated content.
+- Do not delete user-written guidance.
+
+If the user explicitly asks to repair malformed blocks, use the repair workflow when available. If no repair workflow is available, ask before making structural marker changes.
+
+### 7. Verify
+
+Before finishing, check:
+
+- Managed block markers are paired and use stable ids.
+- No `[Project Name]`-style placeholders remain in AgentKit-managed content.
+- Commands in guidance match `package.json` scripts or explicit config/user personalization.
+- `AGENTS.md` references only companion files that exist.
+- `AGENTS.md` references `STACK.md` only when `STACK.md` exists.
+- AI adapters point to `AGENTS.md` and do not duplicate full guidance.
+- Missing configured files were created or explicitly deferred with a reason.
+- No application source files, lockfiles, package manifests, or CI files were modified.
+
+Docs-only update does not require running the project's test/build commands.
+
+### 8. Report
+
+Tell the user:
+
+- Files updated
+- Files created
+- Files skipped because they were unmanaged
+- Files deferred because managed blocks were malformed
+- Stale facts fixed
+- Stack and package manager inferred
+- Commands inferred
+- Config values used
+- Assumptions made
+
+Keep the report concise.