ystack 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (22) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/LICENSE +21 -0
  3. package/LINTING.md +198 -0
  4. package/PHILOSOPHY.md +132 -0
  5. package/PLAN.md +515 -0
  6. package/README.md +103 -0
  7. package/RUNTIMES.md +199 -0
  8. package/bin/cli.js +973 -0
  9. package/hooks/context-monitor.js +30 -0
  10. package/hooks/session-start.sh +35 -0
  11. package/hooks/workflow-nudge.js +107 -0
  12. package/package.json +39 -0
  13. package/skills/address-review/SKILL.md +244 -0
  14. package/skills/build/SKILL.md +246 -0
  15. package/skills/build/resources/plan-checker.md +121 -0
  16. package/skills/docs/SKILL.md +160 -0
  17. package/skills/go/SKILL.md +216 -0
  18. package/skills/go/resources/executor.md +57 -0
  19. package/skills/import/SKILL.md +306 -0
  20. package/skills/pr/SKILL.md +152 -0
  21. package/skills/review/SKILL.md +184 -0
  22. package/skills/scaffold/SKILL.md +549 -0
package/skills/pr/SKILL.md ADDED
@@ -0,0 +1,152 @@
1
+ ---
2
+ name: pr
3
+ description: >
4
+ Create a pull request after verification and docs are updated. Runs final checks,
5
+ detects doc gaps, and delegates to the project's pr-draft skill if available.
6
+ Use this skill when the user says 'pr', '/pr', 'ship', 'ship it', 'create pr',
7
+ 'open pr', 'ready to merge', 'let's ship', or after /review and /docs complete.
8
+ user-invocable: true
9
+ ---
10
+
11
+ # /pr — Ship It
12
+
13
+ You are the final step of the ystack workflow. You verify everything is ready, then create a pull request.
14
+
15
+ ## Phase 0: Pre-flight Checks
16
+
17
+ Run all checks before creating the PR. If any fail, stop and report.
18
+
19
+ ### 1. Verification status
20
+
21
+ Check if `/review` has been run:
22
+ ```bash
23
+ ls .context/*/PLAN.md 2>/dev/null
24
+ ```
25
+
26
+ If a PLAN.md exists, check whether all success criteria have been verified. If not:
27
+ > Success criteria haven't been verified. Run `/review` first?
28
+
29
+ ### 2. Documentation check
30
+
31
+ Detect if code changes affect documented modules:
32
+
33
+ ```bash
34
+ # Get changed files
35
+ git diff main...HEAD --stat
36
+
37
+ # Check if any changed packages map to doc pages
38
+ # Read ystack.config.json or scan docs structure
39
+ ```
40
+
41
+ If code changed in a module that has docs, but no docs files were modified in this branch:
42
+ > Code changes in **payments** but docs at `docs/src/content/shared/payments/` weren't updated.
43
+ > Run `/docs` to update, or confirm docs don't need changes.
44
+
45
+ If the user confirms no docs needed, proceed.
46
+
47
+ ### 3. Lint and typecheck
48
+
49
+ ```bash
50
+ pnpm fix 2>/dev/null # or the project's lint fix command
51
+ pnpm typecheck 2>/dev/null
52
+ pnpm check 2>/dev/null
53
+ ```
54
+
55
+ If any fail, report the errors and offer to fix.
56
+
57
+ ### 4. Clean working tree
58
+
59
+ ```bash
60
+ git status
61
+ ```
62
+
63
+ All changes should be committed. If there are unstaged changes, ask the user what to do.
64
+
65
+ ## Phase 1: Create PR
66
+
67
+ ### If project has `pr-draft` skill
68
+
69
+ Delegate to the project's `pr-draft` skill. It knows the project's PR conventions, monorepo grouping, and section format.
70
+
71
+ > Delegating to `pr-draft` for PR creation...
72
+
73
+ ### If no `pr-draft` skill
74
+
75
+ Create the PR directly:
76
+
77
+ 1. **Ensure branch is pushed:**
78
+ ```bash
79
+ git push -u origin HEAD
80
+ ```
81
+
82
+ 2. **Generate PR title** — Conventional Commits format:
83
+ ```
84
+ feat(payments): add refund reason tracking
85
+ ```
86
+
87
+ 3. **Generate PR body** from the plan and changes:
88
+
89
+ ```markdown
90
+ ## Summary
91
+
92
+ - [What was built and why, 1-3 bullets from DECISIONS.md]
93
+
94
+ ## Changes
95
+
96
+ - [Grouped by package/module from the diff]
97
+
98
+ ## Verification
99
+
100
+ - [Success criteria from PLAN.md, marked as checked]
101
+
102
+ ## Test Plan
103
+
104
+ - [ ] `pnpm typecheck` passes
105
+ - [ ] `pnpm check` passes
106
+ - [ ] [Feature-specific manual test steps]
107
+ ```
108
+
109
+ 4. **Ask about PR status:**
110
+ > Create as **draft** or **ready for review**?
111
+
112
+ 5. **Create the PR:**
113
+ ```bash
114
+ gh pr create --title "<title>" --body "<body>" [--draft]
115
+ ```
116
+
117
+ ## Phase 2: Clean Up
118
+
119
+ After the PR is created:
120
+
121
+ 1. **Close beads** (if Beads is available):
122
+ ```bash
123
+ # Verify all feature beads are closed
124
+ bd show <bead-id>
125
+ ```
126
+
127
+ 2. **Archive `.context/`** — don't delete, just note it's done:
128
+ ```
129
+ Feature context at .context/<feature-id>/ can be cleaned up.
130
+ ```
131
+
132
+ 3. **Report:**
133
+ ```
134
+ PR created: <URL>
135
+
136
+ ## Summary
137
+ - Feature: <name>
138
+ - Commits: N
139
+ - Files changed: N
140
+ - Docs updated: yes/no
141
+ - All criteria verified: yes
142
+ ```
143
+
144
+ ---
145
+
146
+ ## What This Skill Does NOT Do
147
+
148
+ - **Does not write code.** That's `/go`.
149
+ - **Does not review code.** That's `/review`.
150
+ - **Does not update docs.** That's `/docs`. But it DOES check if docs need updating.
151
+ - **Does not force-push.** Ever.
152
+ - **Does not merge.** Only creates the PR. Merging is a human decision.
package/skills/review/SKILL.md ADDED
@@ -0,0 +1,184 @@
1
+ ---
2
+ name: review
3
+ description: >
4
+ Code review and goal-backward verification against success criteria from PLAN.md.
5
+ Use this skill when the user says 'review', '/review', 'check my work', 'verify',
6
+ 'did it work', 'is it done', 'review the changes', or after /go completes and
7
+ the user wants to verify the implementation before shipping.
8
+ user-invocable: true
9
+ ---
10
+
11
+ # /review — Code Review + Verification
12
+
13
+ You are the quality gate of the ystack agent harness. You do two things:
14
+
15
+ 1. **Goal-backward verification** — check that the codebase delivers what the plan promised
16
+ 2. **Code review** — check the diff against project standards
17
+
18
+ You do NOT trust summaries or task completion claims. You check the actual code.
19
+
20
+ ## Phase 0: Load Context
21
+
22
+ 1. Find the active plan and summary:
23
+ ```bash
24
+ ls .context/*/PLAN.md 2>/dev/null
25
+ ```
26
+
27
+ 2. If multiple features exist, ask which to review. If only one, proceed.
28
+
29
+ 3. Read:
30
+ - `.context/<feature-id>/PLAN.md` — the success criteria
31
+ - `.context/<feature-id>/DECISIONS.md` — the locked decisions
32
+ - `.context/<feature-id>/SUMMARY.md` — what `/go` claims it did (if exists)
33
+
34
+ 4. Get the diff — all changes since before `/go` ran:
35
+ ```bash
36
+ git diff main...HEAD --stat
37
+ git diff main...HEAD
38
+ ```
39
+ If not on a feature branch, use the commits from `/go` (check SUMMARY.md for commit hashes).
40
+
41
+ ## Phase 1: Goal-Backward Verification
42
+
43
+ For each success criterion in PLAN.md, verify it against the actual codebase. Do NOT read the SUMMARY.md and trust it — check the code yourself.
44
+
45
+ **For each criterion, run a concrete check:**
46
+
47
+ | Criterion type | How to verify |
48
+ |---------------|--------------|
49
+ | "Column X exists on table Y" | Read the schema file, grep for the column name |
50
+ | "Endpoint accepts field X" | Read the route handler, check the Zod schema or request parsing |
51
+ | "Component renders X" | Read the component file, check it imports and renders the element |
52
+ | "Types exported from package" | Read the package's index.ts or types file, check the export |
53
+ | "Tests pass" | Run `pnpm test --filter=<package>` |
54
+ | "Typecheck passes" | Run `pnpm typecheck` |
55
+ | "Lint passes" | Run `pnpm check` or `pnpm fix` |
56
+
57
+ **Output a verification table:**
58
+
59
+ ```markdown
60
+ ## Verification
61
+
62
+ | # | Criterion | Status | Evidence |
63
+ |---|-----------|--------|----------|
64
+ | 1 | `refundReason` column exists on `transactions` table | PASS | `packages/db/src/schema.ts:47` — `refundReason: pgEnum(...)` |
65
+ | 2 | POST /api/payments/refund accepts `reason` field | PASS | `apps/api/src/routes/payments.ts:92` — `reason: z.enum([...])` |
66
+ | 3 | Admin transaction detail shows refund reason badge | FAIL | Component exists at `apps/admin/src/components/RefundReasonBadge.tsx` but not imported in `page.tsx` |
67
+ | 4 | Types exported from `@acme/shared` | PASS | `packages/shared/src/types/payments.ts:23` — `export type RefundReason` |
68
+ ```
69
+
70
+ **Include file path and line number as evidence.** "PASS" without evidence is not acceptable.
71
+
72
+ ## Phase 2: Code Review
73
+
74
+ Read the full diff and check against project standards.
75
+
76
+ ### What to check
77
+
78
+ **Security:**
79
+ - SQL injection (raw queries, unsanitized input)
80
+ - XSS (dangerouslySetInnerHTML, unescaped user content)
81
+ - Auth bypass (missing middleware, unchecked permissions)
82
+ - Secrets in code (API keys, tokens, passwords)
83
+ - `target="_blank"` without `rel="noopener"`
84
+
85
+ **Type safety:**
86
+ - Usage of `any` (should be `unknown` or a specific type)
87
+ - Missing return types on exported functions
88
+ - Type assertions (`as`) that could be avoided with narrowing
89
+
90
+ **Code quality:**
91
+ - Matches existing patterns in the modified files
92
+ - No unnecessary abstractions or premature generalization
93
+ - No dead code, unused imports, or commented-out blocks
94
+ - Error handling where needed (API boundaries, user input)
95
+ - No `console.log` or `debugger` left in
96
+
97
+ **Accessibility** (for UI changes):
98
+ - Semantic HTML (`<button>` not `<div onClick>`)
99
+ - ARIA labels on interactive elements
100
+ - Alt text on images
101
+ - Keyboard navigation support
102
+
103
+ **Project conventions:**
104
+ - Read `.claude/rules/` and `CLAUDE.md` for project-specific rules
105
+ - Read `docs/src/content/contributing/` if it exists
106
+ - Check: naming conventions, import patterns, file organization
107
+
108
+ ### What NOT to check
109
+
110
+ - Things the linter already catches (formatting, semicolons, bracket style)
111
+ - Code that wasn't changed in this feature
112
+ - Style preferences that aren't in the project rules
113
+
114
+ ## Phase 3: Report
115
+
116
+ Output the full review:
117
+
118
+ ```markdown
119
+ ## Review Results
120
+
121
+ ### Verification: X/Y PASS
122
+
123
+ [Verification table from Phase 1]
124
+
125
+ ### Code Review
126
+
127
+ #### Issues (N found)
128
+
129
+ - **[SEVERITY]** `file/path.ts:LINE`
130
+ Description of the issue.
131
+ Suggested fix: ...
132
+
133
+ - **[SEVERITY]** `file/path.ts:LINE`
134
+ Description of the issue.
135
+
136
+ #### No Issues Found In
137
+ - Security
138
+ - Type safety
139
+ - Accessibility
140
+
141
+ ### Overall Verdict
142
+
143
+ **PASS** — All criteria met, no blocking issues.
144
+
145
+ or
146
+
147
+ **NEEDS FIX** — N criteria failed, M issues found.
148
+ [List specific fixes needed]
149
+ ```
150
+
151
+ **Severity levels:**
152
+ - **BLOCK** — Must fix before shipping. Security issues, failed success criteria, broken types.
153
+ - **WARN** — Should fix. Missing accessibility, weak error handling, style violations.
154
+ - **NOTE** — Consider fixing. Minor improvements, not blocking.
155
+
156
+ ## Phase 4: Offer Fixes
157
+
158
+ If there are BLOCK or WARN issues:
159
+
160
+ > Found N issues. Want me to fix them?
161
+ >
162
+ > **Blocking:**
163
+ > 1. RefundReasonBadge not imported in page.tsx
164
+ >
165
+ > **Warnings:**
166
+ > 1. Missing aria-label on badge component
167
+ >
168
+ > I can fix these now, or you can address them manually.
169
+
170
+ If the user says yes, fix the issues directly — make the changes, run verification again, and commit. Use a `fix(<scope>): <description>` commit message.
171
+
172
+ If all criteria PASS and no BLOCK issues:
173
+
174
+ > All clear. Ready for `/docs` and `/pr`.
175
+
176
+ ---
177
+
178
+ ## What This Skill Does NOT Do
179
+
180
+ - **Does not trust SUMMARY.md.** It reads the actual code.
181
+ - **Does not review code outside the feature.** Only the current diff.
182
+ - **Does not update docs.** That's `/docs`.
183
+ - **Does not create PRs.** That's `/pr`.
184
+ - **Does not rewrite working code.** If it passes criteria and has no issues, it's done.