@mriekki/project-forge 0.0.0-stage → 2.0.0

package/assets/generated/core/core/skills/cleanup-branches/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: cleanup-branches
+description: Preview-first cleanup of completed short-lived Git branches locally and on the configured remote, using merged-PR evidence and explicit destructive authorization.
+argument-hint: "[optional branch name/prefix]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Cleanup Branches
+
+`/cleanup-branches` removes completed short-lived branches without treating branch-name patterns or Git ancestry alone as proof that deletion is safe.
+
+Existing repository conventions outrank Project Forge defaults. Preserve configured default/protected branches, release/integration branches, and any branch the repository intentionally keeps long-lived.
+
+Invocation begins read-only.
+
+## 1. Purpose
+
+Use this skill for branch housekeeping outside the normal `/deliver` path, especially when historical feature/fix/chore branches have accumulated.
+
+Normal delivery should clean its own short-lived branch after merge and successful required post-merge default-branch CI. This skill is for backlog cleanup, interrupted delivery, or explicit inspection.
+
+## 2. Read-only discovery
+
+Inspect current repository state and resolve the actual default branch and remotes. Typical evidence includes:
+
+```text
+git status --short --branch
+git branch --show-current
+git branch -vv
+git branch -r
+git remote -v
+git fetch --all --prune --dry-run
+```
+
+When GitHub CLI is available, inspect repository/PR evidence rather than inferring from names alone:
+
+```text
+gh repo view
+gh pr list --state merged
+gh pr list --state open
+```
+
+For each candidate branch, record when observable:
+- local head SHA,
+- remote head SHA,
+- merged PR number/state,
+- PR head ref and head SHA,
+- whether an open PR still references the branch,
+- whether the branch is default/protected/long-lived by repository policy,
+- whether local commits exist beyond the remote/merged PR head.
+
+Do not modify anything during discovery.
+
+## 3. Classification
+
+Classify every observed non-default branch into one of these buckets.
+
+### SAFE TO DELETE
+
+A branch may be classified safe only when evidence shows it is completed and unchanged since completion. Strong evidence is:
+- a merged PR exists for that exact head branch,
+- the observed branch head still matches the PR head SHA (or the branch is already absent remotely),
+- no open PR references the branch,
+- no local-only commits were added after the approved/merged head,
+- it is not the default, protected, release, integration, environment, or intentionally long-lived branch.
+
+A branch fully merged by ancestry may also be safe when repository policy and commit history make that unambiguous.
+
+### REVIEW REQUIRED
+
+Use this when any material evidence is missing or ambiguous, including:
+- no merged PR and ancestry is not conclusive,
+- remote/local heads differ,
+- branch moved after its PR merged,
+- local-only commits exist,
+- an open PR references it,
+- branch purpose/lifecycle is unclear.
+
+### PRESERVE
+
+Always preserve by default:
+- the configured default branch,
+- protected branches,
+- active/open-PR branches,
+- release/integration/environment branches unless repository policy explicitly says otherwise,
+- any branch the human marks to keep.
+
+Never classify by prefix alone.
+
+## 4. Preview
+
+Present a concrete preview before deletion:
+
+```text
+BRANCH CLEANUP PREVIEW
+
+Default branch: <name>
+Working tree: <clean / details>
+
+SAFE TO DELETE
+  <branch>  local=<sha|absent>  remote=<sha|absent>  evidence=<merged PR / ancestry>
+
+REVIEW REQUIRED
+  <branch>  <reason>
+
+PRESERVE
+  <branch>  <reason>
+
+NO CHANGES HAVE BEEN MADE
+```
+
+If no branch is safely deletable, stop after the preview.
+
+## 5. Cleanup gate
+
+For a non-empty verified-safe set, present one bounded destructive gate:
+
+```text
+BRANCH CLEANUP READY
+
+1. Delete verified-safe local + remote branches [GIT + GITHUB WRITE] — recommended
+2. Delete verified-safe remote branches only [GITHUB WRITE]
+3. Delete verified-safe local branches only [GIT WRITE]
+4. Stop [NO ACTION]
+```
+
+Only the selected option authorizes the corresponding deletions. Do not include REVIEW REQUIRED branches in the bounded action.
+
+## 6. Revalidate before deletion
+
+Immediately before any deletion:
+- fetch/prune remote state,
+- re-resolve the default branch,
+- confirm every candidate branch head still matches the previewed SHA/evidence,
+- confirm no new/open PR now references it,
+- confirm the working tree is safe to switch branches,
+- confirm the current branch is not about to be deleted.
+
+If anything materially changed, stop and return to preview. Do not silently widen the approved set.
+
+## 7. Apply cleanup
+
+Switch to the default branch before deleting the current feature branch and update it with the repository-approved non-rewriting method, normally `git pull --ff-only`.
+
+For each approved remote branch, use the repository's normal remote-deletion mechanism, for example:
+
+```text
+git push origin --delete <branch>
+```
+
+If the remote branch is already absent, treat that as already-clean rather than an error.
+
+For each approved local branch:
+- prefer `git branch -d <branch>` when Git recognizes it as merged,
+- squash/rebase merges may cause `-d` to reject even though the PR is merged,
+- only when merged-PR evidence is exact and the local head has no commits beyond the approved PR head may `git branch -D <branch>` be used under the explicit cleanup authorization.
+
+Never use `-D` merely to bypass uncertainty.
+
+After deletion:
+
+```text
+git fetch origin --prune
+```
+
+## 8. Completion report
+
+Report exactly what happened:
+
+```text
+BRANCH CLEANUP COMPLETE
+
+Deleted remote:
+  ...
+Deleted local:
+  ...
+Already absent:
+  ...
+Preserved / review required:
+  ...
+Default branch: <name>
+Working tree: <state>
+```
+
+Do not claim a branch was deleted unless the resulting local/remote state was observed.
+
+## 9. Relationship to /deliver
+
+`/deliver` owns branch finalization for the work it is actively delivering. `/cleanup-branches` is the standalone maintenance path for accumulated or previously retained branches.

package/assets/generated/core/core/skills/coach/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: coach
+description: "Optional guided engineering learning before, during, or after work using actual repository context: concepts, code walkthroughs, debugging, coding/DSA, SQL, design, system design, interview drills, diagrams, and resources."
+argument-hint: "[topic/work-item] [light|focused|deep|broad] [L1-L6]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Coach
+
+Coaching is optional and never blocks planning, implementation, review, delivery, merge, or work-item completion.
+
+## 1. Context and boundaries
+
+- Read only minimum relevant code/work-item/learning context.
+- Do not edit production code or implement fixes while in Coach mode.
+- Do not invoke subagents.
+- Do not silently broaden scope.
+- Do not pin/request/switch to a premium model automatically.
+- Distinguish actual implementation/understanding from AI-generated work and study.
+
+## 2. Depth
+
+```text
+Light    — quick explanation/check
+Focused  — one topic, moderate depth
+Deep     — trace/apply/debug/defend one topic
+Broad    — survey related areas and find gaps
+Coach recommends
+```
+
+Do not force the human to choose a depth when their prompt already makes intent clear.
+
+## 3. Learning levels
+
+```text
+L1 Recognize
+L2 Explain
+L3 Trace
+L4 Apply / Debug
+L5 Defend / Design
+L6 Interview Ready
+```
+
+These measure understanding, not seniority. Do not inflate mastery.
+
+## 4. Modes and lab routing
+
+Support:
+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.
+
+Use installed learning assets when present; do not assume they exist.
+
+For a structured walkthrough of implementation changes across a Git/PR/commit change set, prefer `/code-walkthrough`. Coach remains available for ad-hoc explanation of a file, symbol, concept, design choice, or selected code block.
+
+For database learning, use `/coach` for concept teaching, adaptive questioning, gap assessment, and interview pressure. When the task needs concrete repository/database evidence — schema exploration, ORM-to-SQL tracing, query plans, migrations, database debugging, query-to-ERD highlighting, or database-change impact — route to `/db-lab` when that skill is installed.
+
+For system-design learning, use `/coach` for concepts, mental models, adaptive questioning, tradeoff practice, and interview pressure. When the task needs concrete repository/system evidence — architecture/components, runtime scenarios, APIs, dependencies, messaging, failure behavior, capacity/performance, observability, security, deployment, testing, architecture-change impact, or an interactive system view — route to `/system-lab` when installed.
+
+`/db-lab` and `/system-lab` are sibling evidence labs. Do not duplicate a database query-plan deep dive in System Lab or a system-wide availability discussion in Database Lab when the other lab is available.
+
+## 5. Continuous adaptive cadence
+
+```text
+question
+→ human answer
+→ critique/teach
+→ next material question
+```
+
+Do not repeatedly ask whether to continue.
+
+Adapt difficulty:
+- weak answer: teach missing mental model, simplify, ask for own-words explanation;
+- solid: apply/edge case;
+- strong: tradeoff/debug/design;
+- very strong: interviewer pressure or changed scale/assumptions.
+
+For advanced database/system-design work, prefer **prediction before reveal** when practical: ask what the learner expects from a plan, failure, scale change, duplicate message, timeout, or architecture perturbation before showing the strongest evidence. Do not force quiz mode when the learner explicitly wants explanation first.
+
+## 6. Mode guidance
+
+Concept:
+
+```text
+definition → repository/example → diagram if useful → check understanding → application
+```
+
+Debugging:
+
+```text
+symptom → hypotheses → distinguishing evidence → root cause → fix concept → prevention
+```
+
+Do not implement the fix during Coach mode.
+
+Coding/DSA:
+
+```text
+problem → clarifying questions → approach → complexity → code → edge cases/tests → hints → alternatives → feedback
+```
+
+Do not reveal the solution immediately.
+
+SQL/database:
+
+```text
+requirements/schema/query problem
+→ human models or writes SQL
+→ correctness
+→ edge cases/invariants
+→ access patterns + indexing/query plan
+→ transactions/concurrency when relevant
+→ ORM translation when useful
+→ design/interview defense
+```
+
+Treat relational modeling, constraints, normalization, querying, indexes/plans, transactions, ORM translation, migrations, debugging, and design defense as separate competencies rather than one SQL score. Prefer `/db-lab` for hands-on evidence.
+
+System design:
+
+```text
+requirements + constraints
+→ learner states assumptions
+→ architecture/API/data choices
+→ runtime/data/event trace
+→ failure + consistency reasoning
+→ capacity/latency/scaling
+→ security/observability/deployment/testing
+→ alternatives + why-not questions
+→ changed constraint / evolution
+→ design defense
+```
+
+Treat requirements framing, capacity, API design, decomposition, data/storage, caching, messaging, consistency, scaling, availability, performance, deployment, observability, security, cost/complexity, evolution, incident/debugging, testing strategy, tradeoff defense, and interview communication as separate competencies rather than one system-design score. Prefer `/system-lab` for hands-on evidence.
+
+Challenge cargo-cult complexity. Ask credible questions such as `Why not keep the monolith?`, `Why not use the existing relational database?`, `Why not make this synchronous?`, `Why not avoid the cache?`, `Why not wait to shard?`, or `What evidence justifies this queue/service?`.
+
+Interview drill: critique correctness, depth, credibility, structure, concision, overstatement, adaptability to changed constraints, and missed follow-ups.
+
+## 7. Diagrams/resources
+
+Mermaid diagrams in chat may be used for architecture, request/sequence/state/data/CI/deployment/concurrency understanding. Diagrams are ephemeral unless explicitly requested as durable artifacts.
+
+When `/db-lab` or `/system-lab` provides an interactive view, treat it as a disposable projection of current evidence, not a source of truth. The lab should re-discover current evidence when invoked so the human does not need to maintain or manually refresh learning diagrams.
+
+External resources are optional. Prefer official docs/vendor tutorials, then a small number of current high-quality resources. Show 1–3 at a time, not a link dump. Never make external resources an engineering prerequisite.
+
+## 8. Optional learning progress
+
+Only update a learning-progress tracker when the human explicitly chooses to do so. Skipping it has no engineering impact.
+
+A generated lab artifact or completed walkthrough is evidence of learning activity, not automatic mastery. Record demonstrated understanding conservatively and by competency when depth matters.
+
+## 9. Credibility
+
+For interview/portfolio discussion distinguish:
+- actually implemented/used,
+- AI-generated but reviewed/understood,
+- studied/practiced,
+- not yet understood.
+
+Never manufacture professional experience.

package/assets/generated/core/core/skills/code-walkthrough/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: code-walkthrough
+description: "Read-only guided walkthrough of an implementation diff, explaining changed files functionally and technically with optional deeper coaching, tracing, diagrams, quizzes, debugging discussion, and interview practice."
+argument-hint: "[work-item|PR|commit|current] [light|focused|deep]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Code Walkthrough
+
+Purpose: help the developer understand an actual implementation by walking through the changed files in a sensible order and connecting functional behavior to technical design.
+
+`/code-walkthrough` is optional, read-only, and never blocks review, delivery, merge, or work-item completion.
+
+## 1. Boundaries
+
+- Do not edit production code or tests.
+- Do not implement fixes during the walkthrough.
+- Do not commit, push, merge, or modify a PR.
+- Do not update learning-progress files unless the human explicitly chooses that after the walkthrough.
+- Do not invoke subagents.
+- Do not silently broaden the implementation scope.
+- Do not pin/request/switch to a premium model automatically.
+- Distinguish observed implementation evidence from assumptions.
+- Distinguish AI-generated code, developer-reviewed understanding, study, and actual implementation experience when credibility matters.
+
+If a bug, design concern, or missing test is discovered, explain it and offer a return to the normal implementation/review workflow. Do not fix it while in walkthrough mode.
+
+## 2. Resolve the change set
+
+Use Git/GitHub evidence as the source of truth. VS Code Source Control/diff views are visual aids, not workflow state.
+
+Resolve in this order when possible:
+
+```text
+explicit PR / commit / ref
+→ work-item-associated branch or PR supported by evidence
+→ current feature branch versus the merge-base of the configured default branch
+→ current staged/unstaged tracked changes
+→ ask one concise scope question when materially ambiguous
+```
+
+For an explicit PR, use the PR base/head change set and do not silently mix unrelated local changes.
+
+For an active feature branch, prefer the branch change from the default-branch merge base. Identify relevant tracked working changes and call out untracked files explicitly rather than silently omitting them.
+
+For merged work, use the PR, merge commit, or explicit historical commit range.
+
+Never invent branch, work-item, PR, or commit associations.
+
+## 3. Depth
+
+```text
+Light   — what changed, why, and major connections
+Focused — default; behavior, important mechanics, relationships, tests, and learning hooks
+Deep    — important methods/blocks, state/data flow, dependencies, edge cases, failure modes, tests, and tradeoffs
+```
+
+Depth may vary by file. Treat trivial configuration lightly unless it materially affects behavior; spend more depth on implementation anchors.
+
+## 4. Build the walkthrough plan
+
+Before explaining the first file:
+
+1. identify the changed files and change types,
+2. read only enough work-item/requirements context to understand intended behavior,
+3. identify likely implementation anchors and relationships,
+4. order files for understanding rather than alphabetically,
+5. present a concise plan and start with the first meaningful file.
+
+Use repository architecture rather than a fixed stack assumption. A common web-application order may be:
+
+```text
+domain/data model
+→ persistence
+→ service/business logic
+→ API/controller
+→ client model/service/state
+→ UI/component
+→ tests near the behavior they verify
+→ configuration/operational files
+```
+
+An event-driven or systems repository may require a different path. Infer from actual imports, references, paths, changed symbols, tests, and architecture.
+
+## 5. Per-file walkthrough
+
+For each meaningful changed file, cover only what is useful:
+
+```text
+FILE <n> OF <total>
+<path>
+
+ROLE
+Why this file exists in the system.
+
+FUNCTIONAL CHANGE
+What behavior or capability changed.
+
+TECHNICAL CHANGE
+Important classes/functions/data structures/framework mechanisms and how they changed.
+
+HOW THIS CONNECTS
+Upstream/downstream callers, data flow, state flow, persistence, UI, events, or other dependencies.
+
+WHY THIS DESIGN
+Important choice, convention, or tradeoff when evidence supports it.
+
+TESTING
+Relevant tests/evidence and what they do or do not prove. Never claim a test passed unless execution evidence was observed.
+
+LEARNING HOOKS
+Concepts worth understanding more deeply.
+```
+
+For change types:
+- new file: explain why the responsibility now exists;
+- modified file: explain meaningful before-versus-after behavior;
+- deleted file: explain what responsibility disappeared or moved;
+- renamed/moved file: distinguish structural movement from behavioral change.
+
+Group trivial generated/configuration changes when that improves learning, but do not hide behaviorally important files.
+
+## 6. Guided navigation
+
+Default to one file or one tightly related file group at a time. Do not dump the whole implementation at once.
+
+At a natural file boundary, show a compact navigation cue such as:
+
+```text
+NEXT: <suggested file>
+Use: next | deeper | explain this | trace | why this design | diagram | quiz | debug | interview | skip | stop
+```
+
+Interpret these naturally:
+- `next` — continue to the suggested next file;
+- `deeper` — increase depth for the current file/topic;
+- `explain this` — focus on the selected/current method, block, symbol, or diff hunk;
+- `trace` — follow request/data/state/event flow across files;
+- `why this design` — discuss alternatives and tradeoffs grounded in repository context;
+- `diagram` — use an ephemeral Mermaid diagram when useful;
+- `quiz` — briefly switch to adaptive Coach-style understanding questions;
+- `debug` — discuss likely failure modes, evidence, and debugging approach without implementing a fix;
+- `interview` — practice explaining or defending the implementation credibly;
+- `skip` — cover the current file lightly and move on;
+- `stop` — end without affecting engineering status.
+
+Do not repeatedly ask whether to continue when the next action is obvious.
+
+## 7. Tracing and learning depth
+
+When tracing, connect actual call/data/state flow. Example shape only:
+
+```text
+UI/input
+→ client/service
+→ API/handler
+→ application/service logic
+→ persistence/event/system boundary
+→ response/result
+```
+
+Map deeper exploration to the shared learning levels when useful:
+
+```text
+L1 Recognize
+L2 Explain
+L3 Trace
+L4 Apply / Debug
+L5 Defend / Design
+L6 Interview Ready
+```
+
+Use `/coach` for broader concept learning and `/learning-review` for structured assessment after the walkthrough.
+
+## 8. Completion
+
+When the planned change set is covered or the human stops, summarize:
+
+- end-to-end implementation flow,
+- major functional changes,
+- important technical decisions and connections,
+- concepts explored deeply versus lightly,
+- tests/evidence actually observed,
+- learning gaps or topics worth revisiting,
+- optional next learning actions.
+
+Offer only relevant next choices, such as:
+
+```text
+1. /learning-review <same scope> [READ ONLY]
+2. /coach <specific concept> [READ ONLY]
+3. Return to engineering workflow [NO ACTION]
+4. Stop [NO ACTION]
+```
+
+Do not create a new engineering state such as `CODE_WALKTHROUGH_PENDING`. Walkthrough completion is learning evidence, not a delivery gate.