forge-shape

Name: forge-shape
Author: mgratzer

9installs5forks

How to install forge-shape?

mgratzer/forge/forge-shape

$npx -y skills add mgratzer/forge --skill forge-shape

Installs into the current project.

Summary

Shape a vague idea into a clear plan through codebase investigation and convergent one-at-a-time questioning. Use when the user has a rough idea or problem that needs specifying before issue creation.

Files · 1

View on GitHub

SKILL.md

1	# Shape
2
3	Shape a problem and converge on a plan before creating issues.
4
5	## Input
6
7	The idea or problem to shape: $ARGUMENTS
8
9	Optional last parameter: `-- <additional context>`
10
11	If no argument is provided, ask the user what they'd like to shape.
12
13	## Process
14
15	### Step 1: Investigate Context
16
17	Before asking any questions, explore the codebase for related context:
18	- Find existing implementations, patterns, and constraints relevant to the idea
19	- Identify integration points, dependencies, and architectural boundaries
20	- Look for prior attempts or related work (git log, closed issues)
21
22	Check for related Issues in the project's Issue tracker — see [issue-operations](../_shared/issue-operations.md) for search mechanics per provider.
23
24	### Step 2: Shape the Problem
25
26	Converge on a shared design concept through one-at-a-time structured questioning. See [shaping-methodology.md](references/shaping-methodology.md) for why one-at-a-time beats batching, how to provide recommended answers without over-anchoring, walking the dependency tree of decisions, when to challenge, and when to stop.
27
28	If CONTEXT.md exists, read it — use its vocabulary when framing questions and challenging the user's language.
29
30	Loop until the design concept is clear:
31
32	1. Ground the next question in Step 1 findings — never ask what the codebase already answers
33	2. Ask one question with your recommended answer (phrase as "I'd suggest X because Y", not as a decision)
34	3. Wait for the user's response
35	4. Challenge when warranted — if the answer conflicts with CONTEXT.md vocabulary, call it out. If it contradicts what the code does, surface it. If it uses vague or overloaded terms, propose a precise canonical term. Invent concrete scenarios to stress-test fuzzy boundaries.
36	5. Adjust your understanding and pick the next question
37
38	Side effects during shaping — as terms and decisions crystallize:
39	- Resolved term? Update CONTEXT.md inline — don't batch. Add the term with a tight definition and `_Avoid_` aliases if the user was using multiple words for the same concept.
40	- Load-bearing decision? If it's hard to reverse, surprising without context, and the result of a real trade-off — offer to record it as a short ADR in `docs/adr/`. Most decisions don't qualify. Create the directory lazily.
41
42	Stop when the user has accepted recommended answers for several consecutive questions, the remaining questions are taste-level (not decision-level), or the shared design concept is clear enough to summarize.
43
44	Use AskUserQuestion for each individual question. Do not bundle multiple questions into one prompt — that defeats the methodology.
45
46	### Step 3: Explore Approaches (delegate, optional)
47
48	If shaping in Step 2 surfaced a clear approach, skip this step and go to Step 4.
49
50	If multiple plausible approaches remain after shaping (e.g., the design concept allows for several architectural shapes), delegate approach generation to 2-3 parallel sub-agents, each given a radically different design constraint. The value is in contrast — approaches must be structurally different, not variations on the same idea. If the runtime does not support sub-agents, generate the approaches sequentially yourself, deliberately adopting a different constraint lens for each.
51
52	Assign each sub-agent one constraint lens (adapt to the problem):
53	- Minimal — smallest change that addresses the core problem
54	- Reuse-first — maximize use of existing patterns and code
55	- Extensibility-first — optimize for future flexibility
56	- Performance-first — optimize for speed or resource efficiency
57
58	Sub-agent instructions:
59
60	> You are designing one approach to a problem, constrained by a specific design lens. Follow your assigned constraint strictly — do not hedge toward a balanced middle ground.
61	>
62	> Given the codebase findings and shaped design concept provided as input, propose one approach:
63	> - One-line summary
64	> - How it works, referencing specific files and patterns
65	> - Tradeoffs (what you gain, what you give up)
66	> - Relative complexity (Low / Medium / High)
67	> - Risk factors
68
69	Inputs provided to each sub-agent:
70	- Codebase findings from Step 1
71	- Shaped design concept from Step 2
72	- The specific constraint lens to apply
73
74	Expected output: One approach per sub-agent, formatted as above.
75
76	Always include a minimal option. Present the contrasting approaches and let the user choose, combine, or reject all of them.
77
78	### Step 4: Summarize Plan
79
80	Produce a structured summary using the output format below. This summary is the input for `forge-create-issue`.
81
82	The summary is evidence of alignment, not the alignment itself. If the user reads the summary and f

People who liked this also viewed

6 picks

Type

caveman-commitUltra-compressed commit message generator. Cuts noise from commit messages while preserving intent and reasoning. Conventional Commits format. Subject ≤50 chars, body only when "why" isn't obvious. UsSkillsJul 2026259k92k
git-guardrails-claude-codeSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026157k181k
setup-pre-commitSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026152k181k
resolving-merge-conflictsSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026146k181k
using-git-worktreesUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackSkillsJul 2026143k259k
finishing-a-development-branchUse when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanupSkillsJul 2026140k259k

forge-shape

9installs5forks

View on GitHub

How to install forge-shape?

mgratzer/forge/forge-shape

$npx -y skills add mgratzer/forge --skill forge-shape

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Shape
2
3	Shape a problem and converge on a plan before creating issues.
4
5	## Input
6
7	The idea or problem to shape: $ARGUMENTS
8
9	Optional last parameter: `-- <additional context>`
10
11	If no argument is provided, ask the user what they'd like to shape.
12
13	## Process
14
15	### Step 1: Investigate Context
16
17	Before asking any questions, explore the codebase for related context:
18	- Find existing implementations, patterns, and constraints relevant to the idea
19	- Identify integration points, dependencies, and architectural boundaries
20	- Look for prior attempts or related work (git log, closed issues)
21
22	Check for related Issues in the project's Issue tracker — see [issue-operations](../_shared/issue-operations.md) for search mechanics per provider.
23
24	### Step 2: Shape the Problem
25
26	Converge on a shared design concept through one-at-a-time structured questioning. See [shaping-methodology.md](references/shaping-methodology.md) for why one-at-a-time beats batching, how to provide recommended answers without over-anchoring, walking the dependency tree of decisions, when to challenge, and when to stop.
27
28	If CONTEXT.md exists, read it — use its vocabulary when framing questions and challenging the user's language.
29
30	Loop until the design concept is clear:
31
32	1. Ground the next question in Step 1 findings — never ask what the codebase already answers
33	2. Ask one question with your recommended answer (phrase as "I'd suggest X because Y", not as a decision)
34	3. Wait for the user's response
35	4. Challenge when warranted — if the answer conflicts with CONTEXT.md vocabulary, call it out. If it contradicts what the code does, surface it. If it uses vague or overloaded terms, propose a precise canonical term. Invent concrete scenarios to stress-test fuzzy boundaries.
36	5. Adjust your understanding and pick the next question
37
38	Side effects during shaping — as terms and decisions crystallize:
39	- Resolved term? Update CONTEXT.md inline — don't batch. Add the term with a tight definition and `_Avoid_` aliases if the user was using multiple words for the same concept.
40	- Load-bearing decision? If it's hard to reverse, surprising without context, and the result of a real trade-off — offer to record it as a short ADR in `docs/adr/`. Most decisions don't qualify. Create the directory lazily.
41
42	Stop when the user has accepted recommended answers for several consecutive questions, the remaining questions are taste-level (not decision-level), or the shared design concept is clear enough to summarize.
43
44	Use AskUserQuestion for each individual question. Do not bundle multiple questions into one prompt — that defeats the methodology.
45
46	### Step 3: Explore Approaches (delegate, optional)
47
48	If shaping in Step 2 surfaced a clear approach, skip this step and go to Step 4.
49
50	If multiple plausible approaches remain after shaping (e.g., the design concept allows for several architectural shapes), delegate approach generation to 2-3 parallel sub-agents, each given a radically different design constraint. The value is in contrast — approaches must be structurally different, not variations on the same idea. If the runtime does not support sub-agents, generate the approaches sequentially yourself, deliberately adopting a different constraint lens for each.
51
52	Assign each sub-agent one constraint lens (adapt to the problem):
53	- Minimal — smallest change that addresses the core problem
54	- Reuse-first — maximize use of existing patterns and code
55	- Extensibility-first — optimize for future flexibility
56	- Performance-first — optimize for speed or resource efficiency
57
58	Sub-agent instructions:
59
60	> You are designing one approach to a problem, constrained by a specific design lens. Follow your assigned constraint strictly — do not hedge toward a balanced middle ground.
61	>
62	> Given the codebase findings and shaped design concept provided as input, propose one approach:
63	> - One-line summary
64	> - How it works, referencing specific files and patterns
65	> - Tradeoffs (what you gain, what you give up)
66	> - Relative complexity (Low / Medium / High)
67	> - Risk factors
68
69	Inputs provided to each sub-agent:
70	- Codebase findings from Step 1
71	- Shaped design concept from Step 2
72	- The specific constraint lens to apply
73
74	Expected output: One approach per sub-agent, formatted as above.
75
76	Always include a minimal option. Present the contrasting approaches and let the user choose, combine, or reject all of them.
77
78	### Step 4: Summarize Plan
79
80	Produce a structured summary using the output format below. This summary is the input for `forge-create-issue`.
81
82	The summary is evidence of alignment, not the alignment itself. If the user reads the summary and f

People who liked this also viewed

6 picks

Type