From 0d72a265da58fbea794045a2e8725f5db6e3d248 Mon Sep 17 00:00:00 2001 From: Marco Siccardi Date: Tue, 23 Jun 2026 07:46:30 +0200 Subject: [PATCH 1/3] feat(prompts): add implementation loop prompts * Introduce prompts for implementation loop: readiness-check, implementation, self-review, learnings, and human-in-the-loop * Enhance README with new prompt structure and descriptions * Update AGENTS.md to reflect new prompt paths --- AGENTS.md | 25 +++-- README.md | 27 +++-- prompts/loop/01-readiness-check.prompt.md | 51 +++++++++ prompts/loop/02-implementation.prompt.md | 63 +++++++++++ prompts/loop/03-self-review.prompt.md | 66 +++++++++++ prompts/loop/04-learnings.prompt.md | 105 ++++++++++++++++++ prompts/loop/05-human-in-the-loop.prompt.md | 39 +++++++ .../{ => skills}/create-agents-md.prompt.md | 0 .../{ => skills}/create-checkpoint.prompt.md | 0 .../create-project-instructions.prompt.md | 0 prompts/{ => skills}/create-skill.prompt.md | 0 .../create-usercontext-instructions.prompt.md | 0 .../{ => skills}/restore-checkpoint.prompt.md | 0 .../{ => skills}/validate-agents-md.prompt.md | 0 .../validate-project-instructions.prompt.md | 0 prompts/{ => skills}/validate-skill.prompt.md | 0 ...alidate-usercontext-instructions.prompt.md | 0 17 files changed, 358 insertions(+), 18 deletions(-) create mode 100644 prompts/loop/01-readiness-check.prompt.md create mode 100644 prompts/loop/02-implementation.prompt.md create mode 100644 prompts/loop/03-self-review.prompt.md create mode 100644 prompts/loop/04-learnings.prompt.md create mode 100644 prompts/loop/05-human-in-the-loop.prompt.md rename prompts/{ => skills}/create-agents-md.prompt.md (100%) rename prompts/{ => skills}/create-checkpoint.prompt.md (100%) rename prompts/{ => skills}/create-project-instructions.prompt.md (100%) rename prompts/{ => skills}/create-skill.prompt.md (100%) rename prompts/{ => skills}/create-usercontext-instructions.prompt.md (100%) rename prompts/{ => skills}/restore-checkpoint.prompt.md (100%) rename prompts/{ => skills}/validate-agents-md.prompt.md (100%) rename prompts/{ => skills}/validate-project-instructions.prompt.md (100%) rename prompts/{ => skills}/validate-skill.prompt.md (100%) rename prompts/{ => skills}/validate-usercontext-instructions.prompt.md (100%) diff --git a/AGENTS.md b/AGENTS.md index b26ac35..e2334c0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,8 @@ Use this order when files differ: | `specs/` | Normative session-model specification and terminology | | `templates/` | Canonical instruction templates aligned to the spec | | `skills/` | Canonical workflow skills (`SKILL.md` folders) and skill-local resources | -| `prompts/` | Compatibility wrappers that route workflows to canonical skills | +| `prompts/skills/` | Compatibility wrappers that route workflows to canonical skills | +| `prompts/loop/` | Numbered step prompts for the implementation loop (readiness-check → implementation → self-review → learnings → human-in-the-loop); invoke in order, learnings is optional | | `usercontexts/` | User-context instruction examples and validation reports | ## Scope And Precedence For AGENTS.md Files @@ -201,14 +202,20 @@ When `specs/context_aware_ai_session_spec.md` changes, audit and update all impa - User context template: [`templates/usercontext_template.instructions.md`](templates/usercontext_template.instructions.md) - Skill template: [`templates/skill_template/SKILL.md`](templates/skill_template/SKILL.md) - Create prompts: - - [`prompts/create-agents-md.prompt.md`](prompts/create-agents-md.prompt.md) - - [`prompts/create-usercontext-instructions.prompt.md`](prompts/create-usercontext-instructions.prompt.md) - - [`prompts/create-project-instructions.prompt.md`](prompts/create-project-instructions.prompt.md) - - [`prompts/create-skill.prompt.md`](prompts/create-skill.prompt.md) + - [`prompts/skills/create-agents-md.prompt.md`](prompts/skills/create-agents-md.prompt.md) + - [`prompts/skills/create-usercontext-instructions.prompt.md`](prompts/skills/create-usercontext-instructions.prompt.md) + - [`prompts/skills/create-project-instructions.prompt.md`](prompts/skills/create-project-instructions.prompt.md) + - [`prompts/skills/create-skill.prompt.md`](prompts/skills/create-skill.prompt.md) - Validate prompts: - - [`prompts/validate-agents-md.prompt.md`](prompts/validate-agents-md.prompt.md) - - [`prompts/validate-usercontext-instructions.prompt.md`](prompts/validate-usercontext-instructions.prompt.md) - - [`prompts/validate-project-instructions.prompt.md`](prompts/validate-project-instructions.prompt.md) - - [`prompts/validate-skill.prompt.md`](prompts/validate-skill.prompt.md) + - [`prompts/skills/validate-agents-md.prompt.md`](prompts/skills/validate-agents-md.prompt.md) + - [`prompts/skills/validate-usercontext-instructions.prompt.md`](prompts/skills/validate-usercontext-instructions.prompt.md) + - [`prompts/skills/validate-project-instructions.prompt.md`](prompts/skills/validate-project-instructions.prompt.md) + - [`prompts/skills/validate-skill.prompt.md`](prompts/skills/validate-skill.prompt.md) +- Loop prompts: + - [`prompts/loop/01-readiness-check.prompt.md`](prompts/loop/01-readiness-check.prompt.md) + - [`prompts/loop/02-implementation.prompt.md`](prompts/loop/02-implementation.prompt.md) + - [`prompts/loop/03-self-review.prompt.md`](prompts/loop/03-self-review.prompt.md) + - [`prompts/loop/04-learnings.prompt.md`](prompts/loop/04-learnings.prompt.md) _(optional)_ + - [`prompts/loop/05-human-in-the-loop.prompt.md`](prompts/loop/05-human-in-the-loop.prompt.md) - Extracted skills index: [`skills/README.md`](skills/README.md) - Sample user context instructions: [`usercontexts/sample_usercontext.instructions.md`](usercontexts/sample_usercontext.instructions.md) diff --git a/README.md b/README.md index 121a1ca..4aa4555 100644 --- a/README.md +++ b/README.md @@ -68,14 +68,23 @@ ai-context-kit/ ├── LICENSE # MIT License file │ ├── prompts/ # Composition prompt wrappers -│ ├── create-usercontext-instructions.prompt.md # Generate user context instruction files -│ ├── create-project-instructions.prompt.md # Generate project-context AGENTS.md files -│ ├── create-agents-md.prompt.md # Generate AGENTS.md files -│ ├── create-skill.prompt.md # Generate skill files -│ ├── validate-usercontext-instructions.prompt.md # Validate user context files -│ ├── validate-project-instructions.prompt.md # Validate project-context AGENTS.md files -│ ├── validate-agents-md.prompt.md # Validate AGENTS.md files -│ └── validate-skill.prompt.md # Validate skill files +│ ├── skills/ # Skill-wrapper prompts (route to canonical skills) +│ │ ├── create-usercontext-instructions.prompt.md # Generate user context instruction files +│ │ ├── create-project-instructions.prompt.md # Generate project-context AGENTS.md files +│ │ ├── create-agents-md.prompt.md # Generate AGENTS.md files +│ │ ├── create-skill.prompt.md # Generate skill files +│ │ ├── create-checkpoint.prompt.md # Capture session state as a checkpoint +│ │ ├── restore-checkpoint.prompt.md # Restore session state from a checkpoint +│ │ ├── validate-usercontext-instructions.prompt.md # Validate user context files +│ │ ├── validate-project-instructions.prompt.md # Validate project-context AGENTS.md files +│ │ ├── validate-agents-md.prompt.md # Validate AGENTS.md files +│ │ └── validate-skill.prompt.md # Validate skill files +│ └── loop/ # Implementation loop prompts (invoke in order) +│ ├── 01-readiness-check.prompt.md # Assess the target slice before any changes +│ ├── 02-implementation.prompt.md # Execute the approved step on a feature branch +│ ├── 03-self-review.prompt.md # Review and emit STATUS: PASS or BLOCKED +│ ├── 04-learnings.prompt.md # Capture key lessons (optional) +│ └── 05-human-in-the-loop.prompt.md # Commit-readiness checklist; waits for go-ahead │ ├── specs/ │ └── context_aware_ai_session_spec.md # Specification for AI session management @@ -110,7 +119,7 @@ ai-context-kit/ - "Review this code for security issues" - "Run the AGENTS validation workflow and list blocking issues" -`prompts/` are available as composition wrappers, while canonical workflow logic lives in `skills/`. +`prompts/skills/` are composition wrappers that route to canonical skills. `prompts/loop/` contains the numbered implementation loop prompts (readiness-check → implementation → self-review → learnings → human-in-the-loop). Canonical workflow logic lives in `skills/`. --- diff --git a/prompts/loop/01-readiness-check.prompt.md b/prompts/loop/01-readiness-check.prompt.md new file mode 100644 index 0000000..9202d23 --- /dev/null +++ b/prompts/loop/01-readiness-check.prompt.md @@ -0,0 +1,51 @@ +--- +description: 'Readiness check — assess the target slice and produce a readiness report before any implementation begins.' +--- + +# Readiness Check + +Do not start implementation yet. + +Read `AGENTS.md` first and follow its precedence and role guidance throughout. + +Then read each of the following files in full if they exist: +- `docs/implementation-backlog.md` +- `specs/` — all specification files relevant to the target slice + (fall back to `docs/specs/` if `specs/` is absent) +- `docs/adrs/README.md` and every ADR file listed for the target slice +- `docs/use-cases/README.md` and every use-case file linked for the target slice + +For arc42 architecture documentation, check whether a `docs/arc42/` folder exists: +- If it exists, read `docs/arc42/05-building-block-view.md` and + `docs/arc42/10-quality-requirements.md` in full. +- If it does not exist, note this in the readiness report and recommend that + the user consider adopting arc42 for structured architecture documentation. + Do not block the readiness assessment on its absence. + +Do not proceed to the readiness assessment until all available files above have been read. + +Inspect `src/` and `tests/` to confirm the current solution structure. +Check `.agents/skills/` for any applicable skills. + +Explicitly list in the readiness report: +- which skills under `.agents/skills/` apply to this slice +- if arc42 docs are present: which sections are likely to need updating after + implementation, and which skill under `.agents/skills/` covers each one + +If the user named a slice or task, target that. +If not, determine the target in this order: +1. Check the `Current Objectives` section of `AGENTS.md` for a single clear active item. +2. If that is ambiguous, check `docs/implementation-backlog.md` for the first + unstarted or in-progress item. +3. If neither gives a single unambiguous target, stop and ask the user to name + the slice or task explicitly. Do not guess. + +Determine: +- whether the target is implementation-ready, needs definition first, + or is blocked by an unresolved ADR +- the single next smallest meaningful step (code, tests, docs, or definition) +- which files in `src/` and `tests/` would be touched + +Reply with a short readiness report covering the above, +plus any visibility gaps or missing context. +Stop and wait for explicit go-ahead before making any changes. \ No newline at end of file diff --git a/prompts/loop/02-implementation.prompt.md b/prompts/loop/02-implementation.prompt.md new file mode 100644 index 0000000..a1fc515 --- /dev/null +++ b/prompts/loop/02-implementation.prompt.md @@ -0,0 +1,63 @@ +--- +description: 'Implementation — execute the single step approved in the readiness report on a dedicated feature branch.' +--- + +# Implementation + +Proceed with the implementation step you proposed in the readiness report. + +Tool preference: +- prefer MCP tools over command line tools for repository actions when available in the current session +- use shell commands as a fallback and state the reason briefly + +Use the context already read in the readiness step — do not re-read those files +unless session context was lost. +If context was lost, re-read the following files before proceeding: +- `AGENTS.md` +- `specs/` — all specification files relevant to the target slice +- `docs/implementation-backlog.md` (if it exists) +- `docs/arc42/05-building-block-view.md` and `docs/arc42/10-quality-requirements.md` + (if `docs/arc42/` exists) +- `docs/adrs/README.md` and every ADR file for the target slice (if it exists) +- `docs/use-cases/README.md` and every use-case file for the target slice (if it exists) + +Also use: +- applicable project-local prompts and skills from `.agents/` +- available session skills identified in the readiness step + +Use `.agents/` resources only to the degree they are actually visible in this session. +If a resource is not accessible, state that briefly and continue with verified +filesystem context. + +Rules: +- if the current branch is `main`, `master`, `dev`, `develop`, or `development`, + create a dedicated feature branch before making any changes; do not work + directly on any of those branches +- work on the feature branch for this session; do not commit until after review + and explicit user go-ahead +- keep the step narrow and reviewable +- add tests together with meaningful logic; never ship logic without + accompanying tests +- run build and test suite after implementation and include the output + in the report +- do not introduce new dependencies without an explicit decision +- before editing any arc42 section, invoke the corresponding + `arc42-toolkit:arc42-section-NN` skill; do not edit arc42 docs directly + without invoking the skill first +- update relevant arc42 docs and ADRs in the same change when architecture, + persistence shape, or layer boundaries are affected +- preserve Clean Architecture layer boundaries: + Domain → Application → Infrastructure → Presentation +- implement only the slice approved in the readiness step; if readiness + concluded that definition or ADR work is needed first, do that instead + of guessing at code +- if any required repository context or agent resource becomes inaccessible, + stop and ask instead of guessing +- explain important decisions briefly and practically + +At the end, provide: +1. what was implemented +2. which slice or task the step advanced +3. whether the step was code, tests, docs, or feature-definition work +4. what tests were added or updated +5. which docs or ADRs were updated \ No newline at end of file diff --git a/prompts/loop/03-self-review.prompt.md b/prompts/loop/03-self-review.prompt.md new file mode 100644 index 0000000..bfba2da --- /dev/null +++ b/prompts/loop/03-self-review.prompt.md @@ -0,0 +1,66 @@ +--- +description: 'Self-review — review the completed implementation and emit a STATUS: PASS or STATUS: BLOCKED report before proceeding.' +--- + +# Self-Review + +Do not make further changes yet. + +Tool preference: +- prefer MCP tools over command line tools for repository actions when available in the current session +- use shell commands as a fallback and state the reason briefly + +Review the implementation that was just completed. + +Purpose: +- review the change +- find concrete issues or confirm that none were found + +Primary inputs: +- the implementation report from the previous step +- the changed files and their diffs +- the tests and docs touched by the change +- build and test output if available + +Use the context already read in the readiness step — ADRs, use cases, and +architecture files are already loaded. +Do not redo the readiness step or perform broad repository discovery. +Read only files that were not part of the original readiness context and are +needed to judge the touched code correctly. + +Prioritize findings in this order: +- bugs and behavioral regressions +- Clean Architecture layer violations + (Domain → Application → Infrastructure → Presentation) +- missing or weak tests +- documentation or ADR drift relative to the implementation +- other risks introduced by the change + +Do not make code changes in this step. +Do not turn the review into a redesign discussion unless needed to explain +a concrete issue. + +Reply with a short review report. + +Open the report with one of these two status lines — nothing before it: + + STATUS: BLOCKED — critical findings must be resolved before proceeding + STATUS: PASS — no blocking findings + +If status is BLOCKED, list findings immediately after, in severity order. +For each finding include: +- priority +- affected file and line if available +- the concrete problem +- why it matters +- the expected correction + +If status is PASS, confirm that explicitly. + +Then include: +1. which files, tests, and docs you reviewed +2. what build and test output you considered +3. any context or diff limitation that reduced review confidence +4. any residual risk or testing gap even if no finding was raised + +Stop and wait for explicit next instruction before making any changes. \ No newline at end of file diff --git a/prompts/loop/04-learnings.prompt.md b/prompts/loop/04-learnings.prompt.md new file mode 100644 index 0000000..9ea6879 --- /dev/null +++ b/prompts/loop/04-learnings.prompt.md @@ -0,0 +1,105 @@ +--- +description: 'Learnings — capture and teach the key lessons from the implementation and review steps; optional but recommended.' +--- + +# Learnings + +Do not make further changes yet. + +Tool preference: +- prefer MCP tools over command line tools for repository actions + when available in the current session +- use shell commands as a fallback and state the reason briefly + +## Stack Context + + + +Primary stack: [PRIMARY_STACK] +Secondary stack: [SECONDARY_STACK] +Architecture: [ARCHITECTURE_PATTERN] +User background: [USER_BACKGROUND] +Learning focus: [LEARNING_FOCUS] + +Before doing anything else, run two checks in order: + +**1. Stack context check** +Scan this prompt for any unfilled placeholders: `[PRIMARY_STACK]`, +`[SECONDARY_STACK]`, `[ARCHITECTURE_PATTERN]`, `[USER_BACKGROUND]`, +`[LEARNING_FOCUS]`. If any placeholder is still present as a literal string, +stop immediately and tell the user which placeholders need to be filled in +before this prompt can be used. + +**2. Self-review status check** +Check the self-review report for its status line: +- If the report opens with `STATUS: BLOCKED`, stop immediately. Do not produce + a learning report. Tell the user: "The self-review is blocked. Resolve the + findings listed in the review report, then re-run the implementation step + before continuing to learnings." +- If the report opens with `STATUS: PASS`, proceed. + +Capture the learnings from the implementation step and the review that followed. + +Purpose: +- teach the user what was learned from this step +- explain the reasoning behind the change +- highlight [PRIMARY_STACK] and [SECONDARY_STACK] lessons when relevant +- map each extracted learning to the user's [USER_BACKGROUND] background + when that comparison would help transfer understanding +- prioritize [LEARNING_FOCUS] given the user's stated focus areas + +Primary inputs: +- the implementation report +- the review report +- the most relevant changed files +- the most relevant tests +- the most relevant docs, if any + +Do not redo the readiness step. +Do not redo the review. +Do not search broadly for extra scope. +If the review found issues, use them as teaching material rather than +turning this into another review. + +Read only the minimum repository guidance needed to explain the touched +code correctly. +Use concrete references to the code and tests from this step. +When presenting learnings, connect them to familiar [USER_BACKGROUND] +concepts, patterns, or mental models where that helps transfer understanding +without forcing weak analogies. + +Focus on: +- what changed and why this was the right step now +- the most important abstraction points or testable boundaries +- what the tests are proving +- the most relevant [PRIMARY_STACK] patterns or pitfalls +- the most relevant [SECONDARY_STACK] details +- the most relevant [ARCHITECTURE_PATTERN] decisions and their rationale +- the most instructive tradeoffs, risks, or mistakes +- what the user should study next + +Do not make code changes in this step. + +Reply with a short learning report: +1. a short explanation of what was implemented and why it mattered +2. the 3 to 5 most important learnings, each mapped to the user's + [USER_BACKGROUND] background where useful +3. which [PRIMARY_STACK] patterns or pitfalls are most worth studying +4. which [SECONDARY_STACK] details are most worth studying +5. which [ARCHITECTURE_PATTERN] decisions are most worth reflecting on +6. which abstraction points or testable boundaries are most worth studying +7. which tests are most worth reading and what they prove +8. which risks, mistakes, or tradeoffs were most instructive +9. which files the user should read next, in order +10. one small follow-up exercise or reflection question for the user +11. any limitation in the available context or evidence for this + learning step + +Stop and wait for explicit next instruction before making any changes. \ No newline at end of file diff --git a/prompts/loop/05-human-in-the-loop.prompt.md b/prompts/loop/05-human-in-the-loop.prompt.md new file mode 100644 index 0000000..f52d4b3 --- /dev/null +++ b/prompts/loop/05-human-in-the-loop.prompt.md @@ -0,0 +1,39 @@ +--- +description: 'Human in the loop — present a commit-readiness summary and checklist; do not commit until the user gives explicit go-ahead.' +--- + +# Human in the Loop + +Do not commit yet. + +Check the self-review report for its status line before doing anything else: +- If the report opens with `STATUS: BLOCKED`, stop immediately. Tell the user: + "The self-review is blocked. Resolve the findings listed in the review report, + then re-run the implementation step before committing." +- If the report opens with `STATUS: PASS`, proceed. + +Summarize the current state of the branch for the user: + +1. What was implemented (from the implementation report) +2. What the self-review found (PASS, or any non-blocking notes) +3. What tests were added or updated +4. What docs or ADRs were updated +5. Whether a learning report was produced this loop (yes / no / skipped) + +Then present this checklist: + +--- +**Ready to commit?** + +- [ ] Self-review status is PASS +- [ ] The implementation matches the slice approved in the readiness report +- [ ] Tests cover the change adequately +- [ ] Docs and ADRs reflect the change +- [ ] No deferred decisions or open tasks should block this commit +- [ ] You have reviewed the summary above and agree with it + +Reply with explicit go-ahead to commit, or name what still needs resolving. +--- + +Do not commit, stage files, or run any git command until the user replies +with an explicit go-ahead. diff --git a/prompts/create-agents-md.prompt.md b/prompts/skills/create-agents-md.prompt.md similarity index 100% rename from prompts/create-agents-md.prompt.md rename to prompts/skills/create-agents-md.prompt.md diff --git a/prompts/create-checkpoint.prompt.md b/prompts/skills/create-checkpoint.prompt.md similarity index 100% rename from prompts/create-checkpoint.prompt.md rename to prompts/skills/create-checkpoint.prompt.md diff --git a/prompts/create-project-instructions.prompt.md b/prompts/skills/create-project-instructions.prompt.md similarity index 100% rename from prompts/create-project-instructions.prompt.md rename to prompts/skills/create-project-instructions.prompt.md diff --git a/prompts/create-skill.prompt.md b/prompts/skills/create-skill.prompt.md similarity index 100% rename from prompts/create-skill.prompt.md rename to prompts/skills/create-skill.prompt.md diff --git a/prompts/create-usercontext-instructions.prompt.md b/prompts/skills/create-usercontext-instructions.prompt.md similarity index 100% rename from prompts/create-usercontext-instructions.prompt.md rename to prompts/skills/create-usercontext-instructions.prompt.md diff --git a/prompts/restore-checkpoint.prompt.md b/prompts/skills/restore-checkpoint.prompt.md similarity index 100% rename from prompts/restore-checkpoint.prompt.md rename to prompts/skills/restore-checkpoint.prompt.md diff --git a/prompts/validate-agents-md.prompt.md b/prompts/skills/validate-agents-md.prompt.md similarity index 100% rename from prompts/validate-agents-md.prompt.md rename to prompts/skills/validate-agents-md.prompt.md diff --git a/prompts/validate-project-instructions.prompt.md b/prompts/skills/validate-project-instructions.prompt.md similarity index 100% rename from prompts/validate-project-instructions.prompt.md rename to prompts/skills/validate-project-instructions.prompt.md diff --git a/prompts/validate-skill.prompt.md b/prompts/skills/validate-skill.prompt.md similarity index 100% rename from prompts/validate-skill.prompt.md rename to prompts/skills/validate-skill.prompt.md diff --git a/prompts/validate-usercontext-instructions.prompt.md b/prompts/skills/validate-usercontext-instructions.prompt.md similarity index 100% rename from prompts/validate-usercontext-instructions.prompt.md rename to prompts/skills/validate-usercontext-instructions.prompt.md From 7a8a5120bda13a52b95374e39c88b8108e56865b Mon Sep 17 00:00:00 2001 From: Marco Siccardi Date: Tue, 23 Jun 2026 09:15:31 +0200 Subject: [PATCH 2/3] fix(prompts): address Copilot review comments on loop prompts - Update prompts/ label and Canonical Authority list in README to reflect skills/ and loop/ subfolders - Update AGENTS.md Source Of Truth precedence entry to distinguish prompts/skills/ wrappers from prompts/loop/ steps - Update source_prompt paths in 8 skill SKILL.md files from prompts/ to prompts/skills/ - Make src/tests directory references flexible in readiness-check prompt - Make arc42 skill invocation conditional on skill availability - Defer architecture layer constraint to project AGENTS.md/ADRs in both implementation and self-review prompts; keep Clean Architecture as example Co-Authored-By: Claude Sonnet 4.6 --- AGENTS.md | 2 +- README.md | 4 ++-- prompts/loop/01-readiness-check.prompt.md | 5 +++-- prompts/loop/02-implementation.prompt.md | 12 +++++++----- prompts/loop/03-self-review.prompt.md | 5 +++-- skills/create-agents-md/SKILL.md | 2 +- skills/create-project-instructions/SKILL.md | 2 +- skills/create-skill/SKILL.md | 2 +- skills/create-usercontext-instructions/SKILL.md | 2 +- skills/validate-agents-md/SKILL.md | 2 +- skills/validate-project-instructions/SKILL.md | 2 +- skills/validate-skill/SKILL.md | 2 +- skills/validate-usercontext-instructions/SKILL.md | 2 +- 13 files changed, 24 insertions(+), 20 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e2334c0..357d582 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,7 @@ Use this order when files differ: 1. **Specification (authoritative, v1.4.2):** `specs/context_aware_ai_session_spec.md` 2. **Templates (canonical structures):** `templates/*.instructions.md` and `templates/skill_template/SKILL.md` 3. **Skills (canonical operational workflows):** `skills/*/SKILL.md` and skill-local references -4. **Prompts (compatibility wrappers):** `prompts/*.prompt.md` (must defer detailed logic to skills) +4. **Prompts:** `prompts/skills/*.prompt.md` (compatibility wrappers — must defer detailed logic to skills); `prompts/loop/*.prompt.md` (implementation loop steps — self-contained workflow prompts) 5. **Samples and validation artifacts (illustrative records):** `usercontexts/*.instructions.md`, related `*.validation.md` ## Repository Map diff --git a/README.md b/README.md index 4aa4555..555f824 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ ai-context-kit/ ├── README.md # This file ├── LICENSE # MIT License file │ -├── prompts/ # Composition prompt wrappers +├── prompts/ # Prompt wrappers and implementation loop │ ├── skills/ # Skill-wrapper prompts (route to canonical skills) │ │ ├── create-usercontext-instructions.prompt.md # Generate user context instruction files │ │ ├── create-project-instructions.prompt.md # Generate project-context AGENTS.md files @@ -130,7 +130,7 @@ When guidance differs across files, use this authority order: 1. `specs/context_aware_ai_session_spec.md` (normative) 2. `templates/` (canonical artifact structures) 3. `skills/` (canonical operational workflows) -4. `prompts/` (composition wrappers) +4. `prompts/skills/` (composition wrappers) and `prompts/loop/` (implementation loop) 5. `usercontexts/` and validation artifacts (illustrative examples) Canonical template structures live in: diff --git a/prompts/loop/01-readiness-check.prompt.md b/prompts/loop/01-readiness-check.prompt.md index 9202d23..d9efcbd 100644 --- a/prompts/loop/01-readiness-check.prompt.md +++ b/prompts/loop/01-readiness-check.prompt.md @@ -24,7 +24,8 @@ For arc42 architecture documentation, check whether a `docs/arc42/` folder exist Do not proceed to the readiness assessment until all available files above have been read. -Inspect `src/` and `tests/` to confirm the current solution structure. +Inspect the primary code and test directories to confirm the current solution structure +(commonly `src/` and `tests/`, but use whatever the project defines). Check `.agents/skills/` for any applicable skills. Explicitly list in the readiness report: @@ -44,7 +45,7 @@ Determine: - whether the target is implementation-ready, needs definition first, or is blocked by an unresolved ADR - the single next smallest meaningful step (code, tests, docs, or definition) -- which files in `src/` and `tests/` would be touched +- which files in the project's code and test directories would be touched Reply with a short readiness report covering the above, plus any visibility gaps or missing context. diff --git a/prompts/loop/02-implementation.prompt.md b/prompts/loop/02-implementation.prompt.md index a1fc515..cbbacbf 100644 --- a/prompts/loop/02-implementation.prompt.md +++ b/prompts/loop/02-implementation.prompt.md @@ -41,13 +41,15 @@ Rules: - run build and test suite after implementation and include the output in the report - do not introduce new dependencies without an explicit decision -- before editing any arc42 section, invoke the corresponding - `arc42-toolkit:arc42-section-NN` skill; do not edit arc42 docs directly - without invoking the skill first +- before editing any arc42 section, check whether the project has an arc42 + helper skill available (e.g. `arc42-toolkit:arc42-section-NN`); if so, + invoke it rather than editing arc42 docs directly - update relevant arc42 docs and ADRs in the same change when architecture, persistence shape, or layer boundaries are affected -- preserve Clean Architecture layer boundaries: - Domain → Application → Infrastructure → Presentation +- preserve the architecture and layer boundaries defined in the project's + AGENTS.md and ADRs (e.g. Clean Architecture: Domain → Application → + Infrastructure → Presentation); do not introduce cross-layer dependencies + that the project has not sanctioned - implement only the slice approved in the readiness step; if readiness concluded that definition or ADR work is needed first, do that instead of guessing at code diff --git a/prompts/loop/03-self-review.prompt.md b/prompts/loop/03-self-review.prompt.md index bfba2da..1d7119d 100644 --- a/prompts/loop/03-self-review.prompt.md +++ b/prompts/loop/03-self-review.prompt.md @@ -30,8 +30,9 @@ needed to judge the touched code correctly. Prioritize findings in this order: - bugs and behavioral regressions -- Clean Architecture layer violations - (Domain → Application → Infrastructure → Presentation) +- architecture or layer boundary violations as defined in the project's + AGENTS.md and ADRs (e.g. Clean Architecture: Domain → Application → + Infrastructure → Presentation) - missing or weak tests - documentation or ADR drift relative to the implementation - other risks introduced by the change diff --git a/skills/create-agents-md/SKILL.md b/skills/create-agents-md/SKILL.md index e94816e..5ed8408 100644 --- a/skills/create-agents-md/SKILL.md +++ b/skills/create-agents-md/SKILL.md @@ -4,7 +4,7 @@ description: "Create concise, repository-specific AGENTS.md files with operation version: "1.0.0" allowed-tools: [Read, Write, Edit] metadata: - source_prompt: "prompts/create-agents-md.prompt.md" + source_prompt: "prompts/skills/create-agents-md.prompt.md" workflow_type: "generation" --- diff --git a/skills/create-project-instructions/SKILL.md b/skills/create-project-instructions/SKILL.md index 8050900..37f681b 100644 --- a/skills/create-project-instructions/SKILL.md +++ b/skills/create-project-instructions/SKILL.md @@ -4,7 +4,7 @@ description: "Create project-context AGENTS.md files using phased discovery, req version: "1.0.0" allowed-tools: [Read, Write, Edit] metadata: - source_prompt: "prompts/create-project-instructions.prompt.md" + source_prompt: "prompts/skills/create-project-instructions.prompt.md" workflow_type: "generation" --- diff --git a/skills/create-skill/SKILL.md b/skills/create-skill/SKILL.md index dc05915..fa73465 100644 --- a/skills/create-skill/SKILL.md +++ b/skills/create-skill/SKILL.md @@ -4,7 +4,7 @@ description: "Create canonical SKILL.md artifacts with deterministic schema, wor version: "1.0.0" allowed-tools: [Read, Write, Edit] metadata: - source_prompt: "prompts/create-skill.prompt.md" + source_prompt: "prompts/skills/create-skill.prompt.md" workflow_type: "generation" --- diff --git a/skills/create-usercontext-instructions/SKILL.md b/skills/create-usercontext-instructions/SKILL.md index df018c2..976b35d 100644 --- a/skills/create-usercontext-instructions/SKILL.md +++ b/skills/create-usercontext-instructions/SKILL.md @@ -4,7 +4,7 @@ description: "Create complete user-context instruction files using a structured version: "1.0.0" allowed-tools: [Read, Write, Edit] metadata: - source_prompt: "prompts/create-usercontext-instructions.prompt.md" + source_prompt: "prompts/skills/create-usercontext-instructions.prompt.md" workflow_type: "generation" --- diff --git a/skills/validate-agents-md/SKILL.md b/skills/validate-agents-md/SKILL.md index f09729b..8a5632b 100644 --- a/skills/validate-agents-md/SKILL.md +++ b/skills/validate-agents-md/SKILL.md @@ -4,7 +4,7 @@ description: "Validate AGENTS.md files for structural completeness, operational version: "1.0.0" allowed-tools: [Read, Write] metadata: - source_prompt: "prompts/validate-agents-md.prompt.md" + source_prompt: "prompts/skills/validate-agents-md.prompt.md" workflow_type: "validation" --- diff --git a/skills/validate-project-instructions/SKILL.md b/skills/validate-project-instructions/SKILL.md index 2c21c12..845332a 100644 --- a/skills/validate-project-instructions/SKILL.md +++ b/skills/validate-project-instructions/SKILL.md @@ -4,7 +4,7 @@ description: "Validate project-context AGENTS.md files for required sections, se version: "1.0.0" allowed-tools: [Read, Write] metadata: - source_prompt: "prompts/validate-project-instructions.prompt.md" + source_prompt: "prompts/skills/validate-project-instructions.prompt.md" workflow_type: "validation" --- diff --git a/skills/validate-skill/SKILL.md b/skills/validate-skill/SKILL.md index 9bf9cca..7735516 100644 --- a/skills/validate-skill/SKILL.md +++ b/skills/validate-skill/SKILL.md @@ -4,7 +4,7 @@ description: "Validate SKILL.md artifacts for schema, quality, safety, portabili version: "1.0.0" allowed-tools: [Read, Write] metadata: - source_prompt: "prompts/validate-skill.prompt.md" + source_prompt: "prompts/skills/validate-skill.prompt.md" workflow_type: "validation" --- diff --git a/skills/validate-usercontext-instructions/SKILL.md b/skills/validate-usercontext-instructions/SKILL.md index 86c2a85..5c4c128 100644 --- a/skills/validate-usercontext-instructions/SKILL.md +++ b/skills/validate-usercontext-instructions/SKILL.md @@ -4,7 +4,7 @@ description: "Validate user-context instruction files against schema, section co version: "1.0.0" allowed-tools: [Read, Write] metadata: - source_prompt: "prompts/validate-usercontext-instructions.prompt.md" + source_prompt: "prompts/skills/validate-usercontext-instructions.prompt.md" workflow_type: "validation" --- From 633fb49ae10655212146ab09adfb31ff32fa9234 Mon Sep 17 00:00:00 2001 From: Marco Siccardi Date: Tue, 23 Jun 2026 09:47:13 +0200 Subject: [PATCH 3/3] chore(plugin): mention implementation loop prompts in plugin and marketplace manifests Updated description and added implementation-loop and workflow-prompts keywords to both plugin.json and marketplace.json for better discoverability. Co-Authored-By: Claude Sonnet 4.6 --- .claude-plugin/marketplace.json | 6 ++++-- .claude-plugin/plugin.json | 6 ++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 12dc8e1..fcacf32 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,7 +11,7 @@ "source": "github", "repo": "MSiccDev/ai-context-kit" }, - "description": "Context-aware AI collaboration skills for creating and validating user context, project AGENTS.md files, and skill artifacts across LLM providers.", + "description": "Context-aware AI collaboration skills and implementation loop prompts for creating and validating user context, project AGENTS.md files, and skill artifacts across LLM providers.", "version": "1.4.2", "license": "MIT", "homepage": "https://github.com/MSiccDev/ai-context-kit", @@ -22,7 +22,9 @@ "skills", "user-context", "ai-collaboration", - "prompt-engineering" + "prompt-engineering", + "implementation-loop", + "workflow-prompts" ] } ] diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index a15c953..24e5bea 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -2,7 +2,7 @@ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "ai-context-kit", "version": "1.4.2", - "description": "Context-aware AI collaboration skills for creating and validating user context, project AGENTS.md files, and skill artifacts across LLM providers.", + "description": "Context-aware AI collaboration skills and implementation loop prompts for creating and validating user context, project AGENTS.md files, and skill artifacts across LLM providers.", "author": { "name": "MSiccDev Software Development", "url": "https://github.com/MSiccDev" @@ -16,6 +16,8 @@ "skills", "user-context", "ai-collaboration", - "prompt-engineering" + "prompt-engineering", + "implementation-loop", + "workflow-prompts" ] }