diff --git a/.ytstack/DECISIONS.md b/.ytstack/DECISIONS.md index 2090f24..f481a3c 100644 --- a/.ytstack/DECISIONS.md +++ b/.ytstack/DECISIONS.md @@ -444,3 +444,27 @@ REVIEW-NOTES 2026-04-24 "Greenfield-flow first-skill is wrong" and docs/concept. - Future ship wrapper is the first concrete test of this stance; concrete fall-out goes to REVIEW-NOTES. **Supersedes:** none. Locks an aspect of wrapper mechanism (2026-04-24) that was implicit until now. + +--- + +## 2026-04-25: M011 scope -- 5-skill cherry-pick from gstack + superpowers + +**Context:** Initial M011 framing (per the 2026-04-25 lifecycle-heuristic decision) was "ship + 1 post-ship skill (canary or document-release)". User requested a re-read of the two comparison articles cited in `docs/concept.md` (dev.to, medium) before locking the milestone scope. The articles clarified: gstack is the only framework with a complete release pipeline (ship / land-and-deploy / canary / document-release / qa); superpowers covers pre-merge closure (verification-before-completion + finishing-a-development-branch + requesting-/receiving-code-review); GSD has no shipping equivalent ("stabilizer, not builder"). + +**Options considered:** +- A) ship + (canary OR document-release) -- gstack-only, original scope, 2 skills +- B) ship + finishing-a-development-branch + requesting-code-review + receiving-code-review + document-release -- mixed cherry-pick, 5 skills (3 superpowers + 2 gstack), balances ship-mechanics with PR-review discipline +- C) ship + land-and-deploy + canary + document-release -- gstack-only complete pipeline, 4 skills, full deployment + monitoring coverage + +**Chose:** B. + +**Reason:** Matches ytstack's "non-overlapping best of both" pattern (concept §3). gstack owns ship-mechanics (VERSION / CHANGELOG / PR-creation / docs sync); superpowers owns PR-review-cycle discipline -- neither framework has the other's strength in the post-summarize arc. Option A leaves a gap (no PR-review skills between summarize and ship). Option C piles up gstack-preamble-drift exposure on 4 wrappers instead of 2 and pulls in deployment + monitoring -- a different skill-class (infra / observability) that belongs in a separate future milestone if demand emerges. B keeps `land-and-deploy`, `canary`, `setup-deploy`, `qa` explicitly out of M011 scope. + +**How to apply:** +- M011 wraps 5 skills total: 2 gstack (`ship`, `document-release`), 3 superpowers (`finishing-a-development-branch`, `requesting-code-review`, `receiving-code-review`). +- Concept §3.6 "Future candidates (deferred)" no longer applies to `requesting-code-review` / `receiving-code-review` -- they move into M011 active scope. Update §3.6 accordingly when M011 lands. +- Order in normal flow: `summarize-task` -> `finishing-a-development-branch` -> `requesting-code-review` -> `receiving-code-review` (loop until approved) -> `ship` -> `document-release`. +- ROADMAP M011 entry updated with the 5-skill scope + cross-reference to this DECISIONS entry. +- All 5 wrappers fall under the "Vendored-preamble drift accepted" decision (2026-04-25); gstack-side preamble calls fail silently on `ship` and `document-release`, ytstack injects own context via wrapper preamble. + +**Supersedes:** none. Refines (not retracts) the M011 scope hint that lived inside the 2026-04-25 "Lifecycle-phase as the curation heuristic" entry; that entry only justified ship in core, not the specific cherry-pick. diff --git a/.ytstack/ROADMAP.md b/.ytstack/ROADMAP.md index fd2bea6..20b17ea 100644 --- a/.ytstack/ROADMAP.md +++ b/.ytstack/ROADMAP.md @@ -1,9 +1,9 @@ --- project: ytstack -last_updated: 2026-04-23T20:30:00Z -total_milestones: 9 +last_updated: 2026-04-25T16:00:00Z +total_milestones: 11 completed_milestones: 9 -current_milestone: review +current_milestone: review (M010 + M011 planned, not started) --- # ytstack Roadmap @@ -27,8 +27,10 @@ Progress legend: `[ ]` todo, `[~]` in progress, `[x]` done, `[-]` skipped. | M007 | Quality Gates (PreToolUse hooks) | **done** | 3 | 3 | | M008 | Publishing & Marketplace | **done (2 user-action)** | 4 | 2 | | M009 | Docs & Community | **done** | 4 | 4 | +| M010 | Workflow Reorder + Brownfield-Without-.ytstack | planned | TBD | 0 | +| M011 | Post-Summarize Lifecycle (5-skill cherry-pick: ship + closure + PR-review + document-release) | planned | TBD | 0 | -**Total:** 39 tasks, 37 done (95%). 2 deferred to user action (git init + push, GitHub repo creation). +**Total:** 39 tasks across M001-M009, 37 done (95%). 2 deferred to user action (git init + push, GitHub repo creation). M010 + M011 task counts pending milestone planning. --- @@ -152,6 +154,54 @@ Progress legend: `[ ]` todo, `[~]` in progress, `[x]` done, `[-]` skipped. --- +## M010 -- Workflow Reorder + Brownfield-Without-.ytstack (planned) + +**Goal:** Two-part scope. Part 1 finishes the greenfield-flow reorder originally planned 2026-04-24. Part 2 adds explicit handling for users running ytstack inside an existing repo that has no `.ytstack/` directory yet (third workflow case alongside greenfield and brownfield-with-.ytstack). + +**Exit criteria:** +- Greenfield smoke-test ("baue mir eine cli...") routes to `office-hours` first (not `plan-milestone` or `init-project`), per DECISIONS 2026-04-24 "Greenfield-flow reorder". +- Brownfield-without-.ytstack case: a user opens an existing project that has no `.ytstack/`, and ytstack offers explicit choice (init-project vs ad-hoc) instead of either silently bypassing or assuming greenfield. +- README documents all three workflows with diagrams; QUICKSTART covers all three. + +**Scope reference:** +- DECISIONS 2026-04-24 "Greenfield-flow reorder" + DECISIONS 2026-04-24 "Wrapper mechanism = shell-exec inject + cross-ref check" originally merged this with wrapper-refactor as a single milestone. The wrapper-refactor part was completed in scope of those decisions; what remains is the workflow-reorder part PLUS the new brownfield-without-.ytstack case identified 2026-04-25. + +**Plan via:** `ytstack:plan-milestone` -- not yet invoked. + +--- + +## M011 -- Post-Summarize Lifecycle (5-skill cherry-pick) (planned) + +**Goal:** Close the lifecycle arc between `summarize-task` and a released version. Today ytstack covers Plan -> Code -> Verify -> Close (`summarize-task`) and stops. Per DECISIONS 2026-04-25 "Lifecycle-phase as the curation heuristic" + 2026-04-25 "M011 scope -- 5-skill cherry-pick", ytstack covers the full dev-loop with a balanced cherry-pick across gstack (ship-mechanics) and superpowers (PR-review-cycle discipline). + +**Exit criteria:** + +Five new wrapper skills, in normal-flow order: + +| # | Skill | Source | Purpose | +|---|---|---|---| +| 1 | `ytstack:finishing-a-development-branch` | `vendor/superpowers/skills/finishing-a-development-branch` | pre-ship closure discipline; ergaenzt verification-before-completion | +| 2 | `ytstack:requesting-code-review` | `vendor/superpowers/skills/requesting-code-review` | prepare + open PR with structured review request | +| 3 | `ytstack:receiving-code-review` | `vendor/superpowers/skills/receiving-code-review` | handle review feedback; classify, apply, re-request (loops with #2 until approved) | +| 4 | `ytstack:ship` | `vendor/gstack/ship` | bumps VERSION, writes CHANGELOG, creates PR-body, pre-merge safety checks, push, PR | +| 5 | `ytstack:document-release` | `vendor/gstack/document-release` | post-ship docs sync (README, ARCHITECTURE, CLAUDE.md, CHANGELOG, VERSION) | + +Plus: README + QUICKSTART updated with the post-summarize loop diagram. + +**Explicit out-of-scope** (per DECISIONS 2026-04-25 "M011 scope" Option C-rejection): +- `land-and-deploy`, `canary`, `setup-deploy` (gstack) -- deployment + monitoring are a different skill-class (infra / observability), planned for a future milestone if demand emerges. +- `qa` (gstack) -- testing methodology overlaps with ytstack's existing TDD + verification-before-completion. + +**Scope reference:** +- DECISIONS 2026-04-25 "M011 scope -- 5-skill cherry-pick from gstack + superpowers" -- justifies the specific cherry-pick after re-reading the dev.to + medium comparison articles cited in `docs/concept.md`. +- DECISIONS 2026-04-25 "Lifecycle-phase as the curation heuristic" -- justifies bringing the ship-arc into ytstack core (lifecycle-gap, requires `.ytstack/` state for SUMMARY/STATE/DECISIONS reads). +- DECISIONS 2026-04-25 "Vendored-preamble drift accepted for wrapped skills" -- applies to all 5 wrappers; gstack-side preamble calls fail silently on `ship` and `document-release`, ytstack injects own context via wrapper preamble. +- Concept §3.6 "Future candidates (deferred)" listed `requesting-code-review` / `receiving-code-review` as v0.2 candidates; M011 pulls them forward. + +**Plan via:** `ytstack:plan-milestone` -- not yet invoked. + +--- + ## How to update this file - When you start a milestone: flip its row to `in-progress` in Overview and in the milestone header diff --git a/.ytstack/STATE.md b/.ytstack/STATE.md index 412e65c..e28663b 100644 --- a/.ytstack/STATE.md +++ b/.ytstack/STATE.md @@ -1,15 +1,15 @@ --- project: ytstack slug: ytstack -last_updated: 2026-04-25T00:50:00Z -current_milestone: review + post-M009-patches +last_updated: 2026-04-25T16:00:00Z +current_milestone: review + post-M009-patches (M010 + M011 planned) active_slice: none active_task: none --- # State -**Status:** Full build cycle complete + post-M009 patches landing. 38/39 roadmap tasks done; 1 deferred (v0.1.0 tag + push -- user action). End-of-cycle review in progress. First interactive smoke-test of `init-project` done 2026-04-24 (partial; surfaced multiple items -- see REVIEW-NOTES). Three workflow infographics now in README as visual reference for upcoming brownfield + debug live-tests. +**Status:** Full build cycle complete + post-M009 patches landing + plugin landscape architecture locked. 38/39 roadmap tasks done; 1 deferred (v0.1.0 tag + push -- user action). End-of-cycle review in progress. First interactive smoke-test of `init-project` done 2026-04-24 (partial; surfaced multiple items -- see REVIEW-NOTES). Three workflow infographics now in README as visual reference for upcoming brownfield + debug live-tests. Sibling-plugin landscape (`ystacks` catalog + `yastack` public + `ydstack` / `yastack-internal` subdirs) shipped 2026-04-25 (afternoon). **Post-M009 patches since 2026-04-23:** using-ytstack skill + session-start hook behavior-priming rewrite; 3 subagent definitions (architect / implementer / verifier); `docs/ux/agent-structure.md` contract; git init + initial scaffold commit; superpowers + gstack subtrees added. @@ -27,6 +27,20 @@ active_task: none - KNOWLEDGE.md gains three lessons: Excalidraw esm.sh version pin (`@0.18.0`), dark mode is `appState.exportWithDarkMode = true` (not color-swap), GFM `
` for default-expanded collapsibles. - GitHub repo metadata edits in flight (user-action): description aligned with new tagline; topics suggested `claude-code claude-code-plugin claude-code-skills ai-agents agentic-workflow anthropic developer-tools project-management tdd yesterday-ai` -- pending user save. +**Session 2026-04-25 (afternoon) -- plugin landscape architecture:** +- Locked 5-plugin family under `Yesterday-AI/ystacks` (private monorepo + catalog hybrid): `ytstack` (engineering), `ydstack` (daily-work), `yastack` (public agent core), `yastack-internal` (yesterday-bundle), `ycstack` (consulting separate-track). +- Three new DECISIONS entries (2026-04-25, merged via PR #1): "Lifecycle-phase as the curation heuristic", "Marketplace consolidates on Yesterday-AI/ystacks (monorepo + catalog hybrid)" (supersedes 2026-04-24 §3.5), "Vendored-preamble drift accepted for wrapped skills". +- README + QUICKSTART now show ystacks as primary install path; legacy self-marketplace path moved to a collapsed `
` block. +- New repos shipped: `Yesterday-AI/ystacks` (private, monorepo + catalog) and `Yesterday-AI/yastack` (public, scaffold). Both have own minimal `.ytstack/` (PROJECT + DECISIONS + STATE) for dogfooding. +- `agentic-foundation` identified as source pool for future ydstack + yastack skill migration (14 + 15 skills). Post-migration purpose of agentic-foundation undecided (archive vs repurpose). +- Naming convention locked: `y{c}stack` (yt/yd/yc/ya) + `-internal` suffix for yesterday-bundles. yastack autonomy framing corrected to Levels-of-AGI 3-4 (Collaborator / Expert), not 4-5. +- `docs/concept.md` §3.5 rewritten to reflect the new architecture (was deferred from PR #1 by design; landed in this STATE-refresh PR). +- Two new milestones surface as next substantive work: + - **M010 Workflow Reorder + Brownfield-Without-.ytstack** -- covers the original M010 greenfield-reorder per DECISIONS 2026-04-24 PLUS adds the new "user runs ytstack inside an existing repo that has no `.ytstack/` yet" case as a third workflow alongside greenfield + brownfield-with-.ytstack. + - **M011 Post-Summarize Lifecycle** -- 5-skill cherry-pick across gstack (`ship`, `document-release`) and superpowers (`finishing-a-development-branch`, `requesting-code-review`, `receiving-code-review`). Scope locked 2026-04-25 after re-reading the comparison articles cited in `docs/concept.md`; full rationale in DECISIONS 2026-04-25 "M011 scope -- 5-skill cherry-pick from gstack + superpowers". Excludes `land-and-deploy`, `canary`, `qa` (different skill-class, deferred). + + Both planned but not started; entries in `.ytstack/ROADMAP.md`. + ``` Progress: [####################] 37/39 tasks (95%) M001 Foundation [######] 6/6 DONE @@ -42,12 +56,15 @@ M009 Docs & Community [####] 4/4 DONE ## Next action -**Live-test brownfield + debugging workflows** using the new infographics as visual reference. Diagrams are now embedded in README; pick a small real task (e.g. "where were we" → resume-session, then drive a task through plan-task → TDD → verify → summarize) and capture deviations in REVIEW-NOTES. +**Plan + start M010 (Workflow Reorder + Brownfield-Without-.ytstack)** OR **Plan + start M011 (Post-Summarize Lifecycle)** -- both planned, neither started. M010 is the unfinished item from 2026-04-24; M011 is new from 2026-04-25 and depends on the lifecycle-heuristic landed today. Background items still open: -1. **Review DRAFT `docs/concept.md`** -- approve, amend, or reject. Until approved, README remains the sole source of truth. +1. **Review DRAFT `docs/concept.md`** -- approve, amend, or reject. Until approved, README remains the sole source of truth. §3.5 was rewritten 2026-04-25 (afternoon) to reflect ystacks consolidation. 2. **Re-do init-project smoke-test in a neutral sandbox path** (avoid "ytstack" substring to isolate the directive-effect from pathname-confound -- see REVIEW-NOTES 2026-04-24). -3. **Tag v0.1.0 + push tag** (only remaining M008 user-action besides eventual public marketplace listing). +3. **Tag v0.1.0 + push tag** (M008 user-action). Command: `git tag -a v0.1.0 -m "v0.1.0: full build cycle complete + plugin landscape architecture locked" && git push origin v0.1.0`. +4. **Save GitHub repo topics** (user-action). Suggested topics: `claude-code claude-code-plugin claude-code-skills ai-agents agentic-workflow anthropic developer-tools project-management tdd yesterday-ai`. Suggested description: "An opinionated OS for AI coding agents. Plan like a PM, execute like a senior eng." (matches README tagline). +5. **Live-test brownfield + debugging workflows** using the new infographics as visual reference. Was previous session's "Next action"; deferred behind the architecture work but still relevant. +6. **Eventual public marketplace listing** (M008 deferred): when ytstack visibility flips from private to public, list it in a public marketplace (e.g. anthropic-skills marketplace, or a future `Yesterday-AI/y-oss`). 4. **Save GitHub repo topics** (user-action; see Session 2026-04-25 additions for suggested list). **Full-cycle review.** See `.ytstack/REVIEW-NOTES.md` for the batch of items flagged during the build. Review categories: diff --git a/docs/concept.md b/docs/concept.md index f9a68b3..b1877b8 100644 --- a/docs/concept.md +++ b/docs/concept.md @@ -217,21 +217,37 @@ Lifecycle + artifact + orchestration pieces that GSD inspired but we re-implemen - `teammate-idle`, `task-created`, `task-completed` -- Agent Teams coordination - `pre-tool-use-edit`, `post-tool-use-bash` -- quality / safety gates -### 3.5 Distribution (self-marketplace, one repo) +### 3.5 Distribution (ystacks monorepo + catalog hybrid) -Per DECISIONS 2026-04-24 "ytstack self-marketplaces, no separate `-marketplace` repo" and "Marketplace name equals plugin name": +Per DECISIONS 2026-04-25 "Marketplace consolidates on Yesterday-AI/ystacks (monorepo + catalog hybrid)" -- supersedes the earlier 2026-04-24 "self-marketplace, no separate -marketplace repo" decision (its "pragmatic, not permanent" caveat invoked once a sibling plugin emerged). -- Plugin source + marketplace manifest both live in `Yesterday-AI/ytstack` (private GitHub repo). `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json` are colocated; no separate `-marketplace` repo exists or is needed. -- `marketplace.json` `"name"` = `"ytstack"` (same as the plugin). Install command is `/plugin marketplace add Yesterday-AI/ytstack` followed by `/plugin install ytstack@ytstack`. -- `marketplace.json` `"source": "./"` for self-reference. -- `plugin.json` is minimal: `name`, `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords`. No explicit `skills` / `agents` / `hooks` path pointers -- Claude Code auto-discovers from `skills/`, `agents/`, `hooks/hooks.json`. Adding those pointer fields triggers duplicate-load errors or schema-validation rejects (verified 2026-04-24 during the install debacle; see KNOWLEDGE.md). -- Private-repo install works via the user's existing `gh auth login` + git credential helper. Background auto-updates require `GITHUB_TOKEN` / `GH_TOKEN` env var. +**Marketplace catalog:** `Yesterday-AI/ystacks` (private monorepo). Hosts both `.claude-plugin/marketplace.json` (the listing Claude Code consumes) and a `plugins//` subdir for each plugin that shares ystacks's lifecycle. Install command: `/plugin marketplace add Yesterday-AI/ystacks` followed by `/plugin install @ystacks`. -**Pragmatic, not permanent:** the single-repo self-marketplace choice is scoped to the current state where ytstack is the only Yesterday-AI stack-plugin. If a sibling stack emerges later (e.g. `ycstack` for non-development workflows), the Yesterday-AI org would likely consolidate into a shared marketplace repo that catalogs multiple stacks -- at which point this decision would be superseded by a new DECISIONS entry covering the multi-stack marketplace layout. Today's form is not an architectural stance against separate marketplace repos; it is the minimum-maintenance choice while there is exactly one stack. +**Five-plugin family** under the `y{c}stack` naming convention plus the `-internal` suffix for yesterday-bundles: + +| Plugin | Location | Visibility | Purpose | +|---|---|---|---| +| `ytstack` | own repo `Yesterday-AI/ytstack` | private (vorerst) | Engineering OS -- this paper's subject | +| `ydstack` | ystacks subdir `plugins/ydstack/` | private | Daily-work, generic productivity skills | +| `ycstack` | TBD (separate design track) | private | Consulting workflows | +| `yastack` | own public repo `Yesterday-AI/yastack` | public | Generic autonomous-agent skills (Levels-of-AGI 3-4); externally installable without ystacks auth | +| `yastack-internal` | ystacks subdir `plugins/yastack-internal/` | private (bundle) | Bundle plugin: yastack + Yesterday-internal service-plugin deps | + +**Per-plugin location decision:** plugins live in own repos when they need independent visibility (yastack public; ytstack pre-existing self-tracking) or release lifecycle (service-repos exist for the service itself). Plugins live as ystacks subdirs when they share ystacks's lifecycle and visibility. + +**Service-plugins:** Yesterday's internal services (`clawrag`, `llm-gateway`, `paperclip-companies`, `agent-services`, `openclaw`, ...) host their own `.claude-plugin/plugin.json` + `skills//SKILL.md` in their respective repos. ystacks marketplace.json lists each service-plugin via `source: { source: "github", repo: "Yesterday-AI/" }` when the service-team is ready. No `yistack` sammelplugin -- per DECISIONS 2026-04-25 (ystacks DECISIONS), service-team owned skills. + +**ytstack's own legacy self-marketplace:** `Yesterday-AI/ytstack/.claude-plugin/marketplace.json` remains functional as a legacy install path (`/plugin marketplace add Yesterday-AI/ytstack` + `/plugin install ytstack@ytstack`). Both paths fetch the identical content. New installs should prefer the consolidated `ystacks` path. A future DECISIONS entry may deprecate the legacy path; today both coexist. + +**plugin.json shape (unchanged from 2026-04-24):** minimal -- `name`, `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords`. No explicit `skills` / `agents` / `hooks` path pointers; Claude Code auto-discovers from `skills/`, `agents/`, `hooks/hooks.json`. Adding pointer fields triggers duplicate-load errors (verified 2026-04-24 during the install debacle; see KNOWLEDGE.md). + +**Auth:** Private-repo install works via the user's existing `gh auth login` + git credential helper. Background auto-updates require `GITHUB_TOKEN` / `GH_TOKEN` env var. ### 3.6 Future candidates (deferred, not open questions) -Logged in `.ytstack/REVIEW-NOTES.md`. Example: wrapping superpowers' `requesting-code-review` / `receiving-code-review` for PR-level review in v0.2. These are deferrals with acceptance criteria, not open architectural questions. +Logged in `.ytstack/REVIEW-NOTES.md`. These are deferrals with acceptance criteria, not open architectural questions. + +**Note (2026-04-25):** the previously-listed v0.2 candidates `requesting-code-review` / `receiving-code-review` (superpowers) have been pulled forward into the M011 active scope per DECISIONS 2026-04-25 "M011 scope -- 5-skill cherry-pick from gstack + superpowers". They are no longer deferred. M011 also adds `finishing-a-development-branch` (superpowers), `ship` (gstack), `document-release` (gstack) to the same scope. ### 3.7 Curation principle (when to add a new skill)