Merge pull request #57 from MSiccDev/development

add 5 step prompt loop for implementation

Author: MSicc

.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"
       ]
     }
   ]

.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"
   ]
 }

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
@@ -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)

README.md

@@ -67,15 +67,24 @@ ai-context-kit/
 ├── README.md                                         # This file
 ├── 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
+├── 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
+│   │   ├── 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/`.
 
 ---
 
@@ -121,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:

prompts/loop/01-readiness-check.prompt.md

@@ -0,0 +1,52 @@
+---
+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 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:
+- 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 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.
+Stop and wait for explicit go-ahead before making any changes.

prompts/loop/02-implementation.prompt.md

@@ -0,0 +1,65 @@
+---
+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, 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 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
+- 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

prompts/loop/03-self-review.prompt.md

@@ -0,0 +1,67 @@
+---
+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
+- 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
+
+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.