@mriekki/lean 0.0.0-stage → 0.1.1

package/assets/generated/core/core/agents/reviewer.agent.md

@@ -0,0 +1,85 @@
+---
+name: Reviewer
+description: Independent read-only review perspective over the configured work-item authority, plan/implementation diff, tests, and repository conventions.
+tools: ["read", "search", "execute"]
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Reviewer
+
+You are the independent review perspective. Start from fresh/minimal context.
+
+## Rules
+
+- Read `.github/lean-workspace.json` when present before assuming requirement authority.
+- Review only sources actually available.
+- Do not edit production code or implement fixes.
+- Do not broaden approved scope.
+- Do not invoke subagents.
+- Do not assume a plan, test result, or previous AI claim is correct.
+- Existing repository conventions and policies outrank Lean defaults.
+- Do not pin/request/switch models automatically.
+- When the host exposes the `execute` tool, use it only for non-mutating inspection or verification commands. Never use shell execution to alter files, the Git index/working tree/refs, dependencies, environments, services, or remote state.
+
+## Plan review
+
+Use the authoritative work-item/requirements plus directly relevant architecture/code.
+
+Check:
+- scope alignment and hidden assumptions,
+- dependencies and integration boundaries,
+- transactions/concurrency/data-loss implications,
+- security/operational risk,
+- test/verification strategy,
+- reversibility,
+- unnecessary complexity.
+
+## Implementation review
+
+Start from:
+- authoritative work-item/requirements,
+- current diff/changed files,
+- relevant tests and observed test evidence,
+- directly relevant repository conventions/architecture.
+
+Review for:
+- requirement fit/correctness,
+- defects/edge cases/regressions,
+- data/security/concurrency/error-handling risk,
+- architecture/maintainability,
+- tests/evidence,
+- UX/accessibility when relevant,
+- repository conventions.
+
+Classify findings:
+
+```text
+BLOCKING
+NON-BLOCKING
+OBSERVATION
+EVIDENCE GAP
+```
+
+Include file/location references when possible and state what was not verified.
+
+End with:
+
+```text
+VERDICT
+READY / CHANGES REQUIRED / INSUFFICIENT EVIDENCE
+```
+
+## Guided ending
+
+After findings use CURRENT STATE, RECOMMENDED NEXT STEP, and a small OPTIONS menu. Reviewer itself does not commit, push, create/merge PRs, or deploy.
+
+When implementation is READY and the human accepts the meaningful local diff, explicitly recommend:
+
+```text
+/deliver
+```
+
+Do not vaguely say `merge when ready`.
+
+If the delivered work item owns production deployment, successful engineering delivery may later hand off to `/production-readiness <deployment-enabler-ID> enable`; Reviewer readiness never authorizes production deployment.

package/assets/generated/core/core/instructions/lean-docs.instructions.md

@@ -0,0 +1,14 @@
+---
+applyTo: "**/*.md"
+---
+
+# Lean Documentation Rules
+
+Respect `.github/lean-workspace.json` and existing repository documentation.
+
+- Do not create Product/Feature Briefs when the profile says they are unused.
+- Do not create duplicate requirement authorities.
+- Label experimental/supplemental briefs clearly.
+- Do not assume a Jira Epic is a Feature Brief.
+- Prefer one useful combined requirements artifact over a conveyor belt of docs when local requirements are appropriate.
+- Keep secret values out of tracked Markdown.

package/assets/generated/core/core/instructions/lean-workflow.instructions.md

@@ -0,0 +1,35 @@
+---
+applyTo: "**"
+---
+
+# Lean Agentic Workflow
+
+Read `.github/lean-workspace.json` when present before assuming how requirements/work items are organized.
+
+Existing team conventions outrank Lean defaults.
+
+Possible sources include Product Briefs, Feature Briefs, Engineering Enablers, Jira Epics/Stories, GitHub Issues, local requirements, ADRs, or small session context.
+
+Use proportional rigor: `LIGHT`, `STANDARD`, `ELEVATED`.
+
+Keep explicit human gates for material requirements, substantive plans, meaningful implementation acceptance, the final merge/delivery decision, and production deployment.
+
+Once a bounded action is authorized, routine mechanics inside that scope should proceed without repeated ceremonial confirmation.
+
+For implementation, establish the repository-appropriate short-lived work branch as routine setup once implementation itself is authorized; do not add a separate branch-creation gate when branch policy/naming and scope are clear.
+
+Continuous modes such as `/grill-me`, `/grill-with-docs`, `/refine-requirements`, `/coach`, `/learning-review`, and `/production-readiness` continue until stopped or naturally complete.
+
+During interactive questioning, prefer concise choice-first options for genuinely bounded human decisions, including `Other / specify` and `Not sure — recommend one` when appropriate. Keep factual/environment-specific values and questions intended to elicit the human's own framing, reasoning, debugging approach, design rationale, or understanding open-ended unless options are later useful as scaffolding.
+
+Shared managed code keeps its canonical owner. When a consumer contains `CORE_BASELINE.json` or `DEPLOYMENT_BASELINE.json`, treat those baselines as ownership evidence. A temporary edit to a shared-managed consumer file may be used to diagnose or prove a reusable defect, but it is not the canonical deliverable.
+
+Before consumer delivery, run available managed-baseline integrity checks. If Core- or Deployment-Kit-managed files have unexplained local drift, stop before staging/commit/push and route the reusable change through `/upstream-fix`. Fix the owning canonical repository, deliver/merge it there under normal gates, then adopt the exact accepted shared commit back into the consumer through the appropriate sync mechanism and retest in consumer context.
+
+Do not manually preserve a private consumer fork of shared managed code merely because the consumer exposed the bug. Consumer-owned product/application files remain normal consumer implementation scope.
+
+After implementation review and local human acceptance, manually invoking `/deliver` authorizes routine short-lived-branch recovery/setup as needed, selective stage/commit/push, PR creation/update, and PR-CI inspection. `/deliver` then stops once for the explicit `Merge and finalize delivery` decision. When the PR still exactly matches the accepted implementation, that one choice combines final PR acceptance, merge authorization, post-merge CI observation, and safe delivered-branch finalization.
+
+Changed PR evidence re-opens the relevant review gate. Merge never implies production-deployment authorization.
+
+Do not pin or automatically escalate models.

package/assets/generated/core/core/learning/CODING_DRILLS.md

@@ -0,0 +1,35 @@
+# Coding / DSA Drills
+
+Optional interview-style practice.
+
+Preferred loop:
+
+```text
+problem
+→ clarifying questions
+→ approach
+→ complexity
+→ code
+→ tests/edge cases
+→ hints only when needed
+→ alternatives
+→ feedback
+```
+
+Patterns:
+
+- arrays/strings,
+- hash map/set,
+- stack/queue,
+- two pointers,
+- sliding window,
+- sorting,
+- binary search,
+- linked lists,
+- trees,
+- BFS/DFS,
+- graph basics,
+- recursion,
+- Big-O.
+
+Prefer project-themed exercises when practical.

package/assets/generated/core/core/learning/DIAGRAM_GUIDE.md

@@ -0,0 +1,19 @@
+# Diagram Guide
+
+Coach may use Mermaid diagrams in chat for:
+
+- architecture,
+- request flow,
+- sequence,
+- state machine,
+- ER/data relationships,
+- CI/CD,
+- deployment,
+- concurrency.
+
+Diagrams are ephemeral by default.
+
+Only save them when explicitly requested.
+
+After a diagram, ask the developer to explain the flow, failure path, boundary,
+and tradeoff.

package/assets/generated/core/core/learning/ENGINEERING_LEARNING_WORKBOOK.md

@@ -0,0 +1,82 @@
+# Engineering Learning Workbook
+
+This is an optional, repository-neutral learning scaffold.
+
+Use the actual project first. The goal is to understand, trace, debug, defend, and explain real engineering work rather than memorize a generic curriculum.
+
+## Learning tools
+
+Use the learning tools for different purposes:
+
+```text
+/code-walkthrough — instructional walkthrough of actual implementation changes
+/learning-review   — assessment of whether the developer can explain and defend the implementation
+/coach             — targeted concept learning, debugging practice, design discussion, drills, and deeper follow-up
+```
+
+All learning activity is optional and never an engineering delivery gate.
+
+## Preferred project-first sequence
+
+When an implementation is stable enough to study, a useful optional sequence is:
+
+```text
+implementation
+→ /code-walkthrough
+→ /learning-review
+→ targeted /coach follow-up where gaps remain
+```
+
+A code walkthrough should connect two views of every meaningful change:
+
+```text
+FUNCTIONAL
+What behavior changed? What can the user/system do now?
+
+TECHNICAL
+Which files, classes, functions, data structures, framework mechanisms, tests, and dependencies make that behavior work?
+```
+
+Then connect the files into an end-to-end flow such as request, data, state, event, persistence, UI, or operational behavior. Use the repository's actual architecture rather than forcing a generic sequence.
+
+During a walkthrough, deeper learning can branch into tracing, diagrams, debugging discussion, design tradeoffs, quizzes, or interview-style explanation. The walkthrough remains read-only; discovered implementation issues return to the normal engineering workflow rather than being silently fixed inside learning mode.
+
+## Suggested practice loop
+
+```text
+concept or changed code
+→ project example
+→ developer explains in own words
+→ trace/apply/debug
+→ tradeoff/failure-mode follow-up
+→ interview-style explanation when useful
+```
+
+## Core areas
+
+- language/framework fundamentals,
+- application/request/data flow,
+- APIs and integration boundaries,
+- database/SQL/ORM behavior,
+- frontend state/validation/accessibility when relevant,
+- testing/debugging/observability,
+- messaging/distributed systems when relevant,
+- CI/CD/deployment/operations,
+- security and data protection,
+- architecture/system design,
+- coding/DSA interview patterns.
+
+Use `LEARNING_MAP.md` to choose a small number of high-value topics and the drill files for focused practice. Learning progress is optional and never an engineering gate.
+
+## Experience credibility
+
+Keep these categories distinct:
+
+```text
+actually implemented/used
+AI-generated but reviewed/understood
+studied/practiced
+not yet understood
+```
+
+A code walkthrough can help move AI-assisted implementation toward reviewed/understood code, but it does not by itself prove mastery or professional experience. Learning must not become a false claim of professional experience.

package/assets/generated/core/core/learning/LEARNING_MAP.md

@@ -0,0 +1,51 @@
+# Optional Engineering Learning Map
+
+Use only when useful.
+
+Tracks:
+
+- language/framework fundamentals,
+- application architecture,
+- APIs/HTTP,
+- databases/SQL/ORM,
+- frontend,
+- testing/debugging,
+- messaging/event-driven systems,
+- Docker/CI/CD/operations,
+- security,
+- system design,
+- coding/DSA,
+- interview communication.
+
+Levels:
+
+```text
+L1 Recognize
+L2 Explain
+L3 Trace
+L4 Apply / Debug
+L5 Defend / Design
+L6 Interview Ready
+```
+
+## How real-code learning maps to the levels
+
+A structured `/code-walkthrough` is especially useful for the first three levels:
+
+```text
+L1 Recognize — identify important changed files, responsibilities, and concepts
+L2 Explain   — describe the functional and technical changes in own words
+L3 Trace     — follow request/data/state/event flow across the implementation
+```
+
+Deeper follow-up can move into:
+
+```text
+L4 Apply / Debug   — reason through failure modes, evidence, and debugging approach
+L5 Defend / Design — explain choices, alternatives, tradeoffs, and architecture
+L6 Interview Ready — explain the implementation clearly under follow-up questioning
+```
+
+Use `/learning-review` to assess understanding after a walkthrough. Use `/coach` for targeted reinforcement, practice, or deeper exploration. These activities are optional and do not affect engineering delivery state.
+
+Coach should recommend only a small number of next topics based on the actual repository/work item.

package/assets/generated/core/core/learning/LEARNING_PROGRESS.md

@@ -0,0 +1,31 @@
+# Optional Learning Progress
+
+This file is optional and never an engineering gate.
+
+| Topic | Level | Evidence/session | Next target | Last reviewed |
+|---|---:|---|---|---|
+| Language/framework | Not assessed | | | |
+| Architecture | Not assessed | | | |
+| Database/SQL | Not assessed | | | |
+| Frontend | Not assessed | | | |
+| Testing/debugging | Not assessed | | | |
+| CI/CD/operations | Not assessed | | | |
+| Security | Not assessed | | | |
+| System design | Not assessed | | | |
+| Coding/DSA | Not assessed | | | |
+
+## Evidence examples
+
+Record evidence only when the human explicitly chooses to update learning progress. Useful evidence can include:
+
+- completed `/code-walkthrough` of a real implementation change set,
+- explained the functional and technical purpose of important changed files,
+- traced a request/data/state/event path across the implementation,
+- explained a design choice and a credible alternative,
+- reasoned through a failure mode or debugging approach,
+- passed a `/learning-review` question at a demonstrated level,
+- completed a focused `/coach` exercise or drill.
+
+A walkthrough is evidence of review/understanding activity, not automatic proof of mastery. Record the demonstrated level conservatively.
+
+Do not update automatically.

package/assets/generated/core/core/learning/RESOURCE_CATALOG.md

@@ -0,0 +1,25 @@
+# Optional External Learning Resources
+
+Prefer:
+
+1. official docs,
+2. official/vendor tutorials,
+3. current high-quality videos,
+4. interactive practice.
+
+Show only 1–3 resources at a time.
+
+Suggested source families:
+
+- language/framework official docs,
+- database vendor docs,
+- MDN for web/HTTP,
+- Docker docs,
+- GitHub/Git docs,
+- testing-framework docs,
+- LeetCode or equivalent for targeted DSA/SQL practice.
+
+When current web access is available, verify specific current video/tutorial
+recommendations rather than relying on stale links.
+
+External resources never become an engineering requirement.

package/assets/generated/core/core/learning/SQL_DRILLS.md

@@ -0,0 +1,27 @@
+# SQL / Database Drills
+
+Optional practice areas:
+
+- joins,
+- aggregates,
+- GROUP BY/HAVING,
+- pagination,
+- deterministic sorting,
+- indexes,
+- query plans,
+- constraints,
+- transactions,
+- concurrency,
+- N+1,
+- ORM translation.
+
+Preferred flow:
+
+```text
+problem
+→ developer writes SQL
+→ correctness
+→ edge cases
+→ indexing/query-plan follow-up
+→ ORM discussion
+```

package/assets/generated/core/core/learning/SYSTEM_DESIGN_DRILLS.md

@@ -0,0 +1,21 @@
+# System-Design Drills
+
+Start from the actual repository.
+
+Possible exercises:
+
+- explain current architecture,
+- scale users/tenants,
+- evolve persistence,
+- multi-instance concurrency,
+- caching,
+- messaging/events,
+- search,
+- file/object storage,
+- authentication/authorization,
+- observability,
+- backup/recovery,
+- incident response,
+- offline/synchronization.
+
+Ask one question at a time and make the developer drive the design.

package/assets/generated/core/core/process/COACHING_GUIDE.md

@@ -0,0 +1,57 @@
+# Optional Coaching Guide
+
+Coaching is first-class but never required for engineering completion.
+
+## Depth
+
+```text
+1. Light — quick explanation/check
+2. Focused — one topic, moderate depth
+3. Deep — trace/apply/debug/defend
+4. Broad — survey related areas and identify gaps
+5. Let Coach recommend
+```
+
+## Modes
+
+```text
+1. Learn a concept
+2. Walk through real project code
+3. Debugging exercise/review
+4. Coding / DSA drill
+5. SQL / database drill
+6. Design defense
+7. System-design exercise
+8. Interview drill
+9. Learning-gap assessment
+10. Recommended learning path
+11. Docs / tutorial / video resources
+12. Return to engineering workflow
+```
+
+For a structured walkthrough of an implementation change set, use `/code-walkthrough`. It is the guided changed-file path under the coaching umbrella: resolve the actual Git/PR/commit diff, order files for understanding, explain functional and technical changes, and allow deeper tracing, diagrams, quizzes, debugging discussion, or interview practice without editing code.
+
+Use `/coach` for broader or ad-hoc concept learning. Use `/learning-review` when the primary goal is to assess whether the developer can explain and defend what was built.
+
+## Levels
+
+```text
+L1 Recognize
+L2 Explain
+L3 Trace
+L4 Apply / Debug
+L5 Defend / Design
+L6 Interview Ready
+```
+
+A useful optional sequence after stable implementation is:
+
+```text
+code walkthrough
+→ learning review
+→ targeted coaching as needed
+```
+
+None of those learning activities is an engineering delivery gate.
+
+Once a coaching mode starts, continue automatically until stop or natural completion. Use the actual repository as the curriculum whenever possible. Learning trackers/resources remain optional.

package/assets/generated/core/core/process/GUIDED_NEXT_STEPS.md

@@ -0,0 +1,48 @@
+# Guided Next Steps
+
+Substantial Lean interactions should not end with a vague `Next:` sentence.
+
+Use evidence-backed guidance:
+
+```text
+CURRENT STATE
+<what is actually known>
+
+RECOMMENDED NEXT STEP
+<one action and why>
+
+OPTIONS
+1. ... [READ ONLY]
+2. ... [MODIFIES DOCS]
+3. ... [MODIFIES FILES]
+4. ... [GIT + GITHUB WRITE]
+5. Stop [NO ACTION]
+
+RECOMMENDED PATH
+<only when multiple future steps are useful>
+```
+
+Show only relevant options.
+
+Standard action labels include:
+
+```text
+[READ ONLY]
+[MODIFIES DOCS]
+[MODIFIES FILES]
+[REQUIREMENTS GATE]
+[HUMAN ACCEPTANCE]
+[GIT WRITE]
+[GITHUB WRITE]
+[GIT + GITHUB WRITE]
+[REMOTE READ ONLY]
+[REMOTE WRITE]
+[PRODUCTION WRITE]
+[NO ACTION]
+```
+
+A selected option authorizes only the bounded action described, except where a skill explicitly defines a continuous session or compound mechanical action.
+
+A manually invoked compound action skill may itself be the bounded authorization for its routine mechanics. `/deliver`, for example, may proceed through safe short-lived-branch setup/recovery, staging, commit, push, PR creation/update, and CI inspection without inserting separate options for each mechanical step. It still stops at its explicit merge/finalize gate and whenever evidence becomes ambiguous or unsafe.
+
+Conversation may continue automatically; consequential decisions remain explicitly gated.

package/assets/generated/core/core/process/HUMAN_GATES.md

@@ -0,0 +1,81 @@
+# Human Gates
+
+Use explicit human gates where consequences warrant them.
+
+Typical gates:
+- workspace/setup acceptance before the first substantive work item,
+- material requirements/scope approval when detailed requirements matter,
+- substantive implementation-plan approval for STANDARD/ELEVATED work,
+- meaningful local implementation/diff acceptance,
+- merge/final-delivery decision after PR CI when the PR still matches the accepted implementation,
+- unrelated/out-of-band branch deletion when not already covered by a bounded delivery/cleanup choice,
+- external/remote/system writes not already covered by an explicitly invoked bounded workflow,
+- first production deployment,
+- destructive recovery/restore,
+- publishing a release/tag.
+
+Workspace/setup acceptance is distinct from generation or installation. Generated files, installed tools, operational dependencies, editor/agent discovery, and human usability are separate facts. A setup script or static diagnostic may provide evidence, but only the human accepts the checkout as ready for the next intended work item.
+
+A human gate is meaningful only when the human understands what is being approved. If the explanation immediately before a gate did not land, re-explain it before asking for approval again. `/wait-what` is the standard read-only communication-repair path when available; invoking it never implies approval of the pending action.
+
+Do not gate routine mechanics individually after a bounded action is already authorized.
+
+## Implementation branch setup
+
+Once implementation itself is authorized, creating/switching to the repository-appropriate short-lived work branch is routine setup, not a separate decision gate, when branch policy/naming and work-item scope are clear and the operation preserves the worktree without history rewriting.
+
+For STANDARD/ELEVATED work, this branch setup follows plan approval. For LIGHT work, it is part of the human-selected implementation action.
+
+Stop only when branch choice/state is ambiguous, unrelated work is present, or the operation would require stash/reset/rebase/force/history rewriting.
+
+## Streamlined /deliver authorization
+
+Because `/deliver` is manually invoked after implementation review and meaningful local acceptance, invoking it is one bounded authorization for routine delivery mechanics within that accepted scope:
+
+```text
+recover/create the short-lived branch when needed
+→ selective stage
+→ staged-diff verification
+→ commit-message generation
+→ commit
+→ normal push
+→ create/update PR
+→ PR-body population
+→ PR-CI inspection/rechecks
+```
+
+Do not separately ask `Create branch?`, `Commit?`, `Push?`, `Create PR?`, or `Check CI?` when those actions remain safe and within scope.
+
+`/deliver` invocation does **not** authorize merge, production deployment, force push, code fixes after CI failure, unrelated branch deletion, scope expansion, or destructive/history-rewriting Git operations.
+
+## Combined final acceptance + merge gate
+
+When the PR head/diff still exactly represents the implementation the human already accepted locally, Reviewer is READY, required PR CI is green, and repository policy/mergeability are satisfactory, final PR acceptance and merge authorization may be combined into one meaningful choice:
+
+```text
+Merge and finalize delivery [HUMAN ACCEPTANCE + GITHUB/GIT WRITE]
+```
+
+That explicit choice covers only the observed PR and its normal short-lived delivered branch. It authorizes:
+- final acceptance of the PR as observed,
+- merge using the approved repository strategy,
+- observation/recheck of required post-merge default-branch CI,
+- safe finalization of that delivered short-lived branch after required post-merge CI is green.
+
+It does not authorize deleting any other branch, bypassing changed evidence, or deploying to production.
+
+If new commits, material diff changes, conflicts, or regressed checks appear after local acceptance, final PR review becomes a real gate again before merge.
+
+If the repository/human explicitly requires branch retention, preserve the delivered branch. If safe cleanup cannot be proven, preserve it and report the exact reason rather than inserting another ceremonial prompt.
+
+A later production deployment, unrelated branch cleanup, release publication, destructive recovery action, or newly changed implementation remains a separate explicit gate.
+
+The principle is:
+
+```text
+conversation continues automatically
+routine mechanics are grouped when safe
+branch setup/finalization are automatic inside explicit bounded workflows
+changed evidence re-opens the relevant review gate
+consequential decisions remain human-controlled
+```