docs(templates): update slash command instructions

Author: TabishB

src/core/templates/slash-command-templates.ts

@@ -1,20 +1,24 @@
 export type SlashCommandId = 'proposal' | 'apply' | 'archive';
 
 const baseGuardrails = `**Guardrails**
-- Default to <100 lines of new code, single-file solutions, and avoid new frameworks unless OpenSpec data requires it.
-- Use pnpm for Node.js tooling and keep changes scoped to the requested outcome.`;
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.`;
 
-const proposalGuardrails = `${baseGuardrails}\n- Ask up to two clarifying questions if the request is ambiguous before editing files.`;
+const proposalGuardrails = `${baseGuardrails}\n- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.`;
 
 const proposalSteps = `**Steps**
-1. Review \`openspec/project.md\`, run \`openspec list\`, and \`openspec list --specs\` to understand current work and capabilities.
-2. Choose a unique verb-led \`change-id\` and scaffold \`proposal.md\`, \`tasks.md\`, and optional \`design.md\` under \`openspec/changes/<id>/\`.
-3. Draft spec deltas in \`changes/<id>/specs/\` using \`## ADDED|MODIFIED|REMOVED Requirements\` with at least one \`#### Scenario:\` per requirement.
-4. Validate with \`openspec validate <id> --strict\` and resolve every issue before sharing the proposal.`;
+1. Review \`openspec/project.md\`, run \`openspec list\` and \`openspec list --specs\`, and inspect related code or docs (e.g., via \`rg\`/\`ls\`) to ground the proposal in current behaviour; note any gaps that require clarification.
+2. Choose a unique verb-led \`change-id\` and scaffold \`proposal.md\`, \`tasks.md\`, and \`design.md\` (when needed) under \`openspec/changes/<id>/\`.
+3. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
+4. Capture architectural reasoning in \`design.md\` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
+5. Draft spec deltas in \`changes/<id>/specs/\` using \`## ADDED|MODIFIED|REMOVED Requirements\` with at least one \`#### Scenario:\` per requirement and cross-reference related capabilities when relevant.
+6. Draft \`tasks.md\` as an ordered list of small, verifiable work items that deliver user-visible progress, include validation (tests, tooling), and highlight dependencies or parallelizable work.
+7. Validate with \`openspec validate <id> --strict\` and resolve every issue before sharing the proposal.`;
 
 const proposalReferences = `**Reference**
 - Use \`openspec show <id> --json --deltas-only\` or \`openspec show <spec> --type spec\` to inspect details when validation fails.
-- Search existing requirements with \`rg -n "Requirement:|Scenario:" openspec/specs\` before writing new ones.`;
+- Search existing requirements with \`rg -n "Requirement:|Scenario:" openspec/specs\` before writing new ones.
+- Explore the codebase with \`rg <keyword>\`, \`ls\`, or direct file reads so proposals align with current implementation realities.`;
 
 const applySteps = `**Steps**
 1. Read \`changes/<id>/proposal.md\`, \`design.md\` (if present), and \`tasks.md\` to confirm scope and acceptance criteria.
@@ -26,13 +30,13 @@ const applyReferences = `**Reference**
 - Use \`openspec show <id> --json --deltas-only\` if you need additional context from the proposal while implementing.`;
 
 const archiveSteps = `**Steps**
-1. Confirm deployment is complete, then move \`changes/<id>/\` to \`changes/archive/YYYY-MM-DD-<id>/\`.
-2. Update \`openspec/specs/\` to capture production behaviour, editing existing capabilities before creating new ones.
-3. Run \`openspec archive <id> --skip-specs\` only for tooling-only work; otherwise ensure spec deltas are committed.
-4. Re-run \`openspec validate --strict\` and review with \`openspec show <id>\` to verify archive changes.`;
+1. Identify the requested change ID (via the prompt or \`openspec list\`).
+2. Run \`openspec archive <id>\` to let the CLI move the change and apply spec updates (use \`--skip-specs\` only for tooling-only work).
+3. Review the command output to confirm the target specs were updated and the change landed in \`changes/archive/\`.
+4. Validate with \`openspec validate --strict\` and inspect with \`openspec show <id>\` if anything looks off.`;
 
 const archiveReferences = `**Reference**
-- Cross-check capabilities with \`openspec list --specs\` and resolve any outstanding validation issues before finishing.`;
+- Inspect refreshed specs with \`openspec list --specs\` and address any validation issues before handing off.`;
 
 export const slashCommandBodies: Record<SlashCommandId, string> = {
   proposal: [proposalGuardrails, proposalSteps, proposalReferences].join('\n\n'),

test/core/init.test.ts

@@ -110,7 +110,8 @@ describe('InitCommand', () => {
 
       const archiveContent = await fs.readFile(claudeArchive, 'utf-8');
       expect(archiveContent).toContain('name: OpenSpec: Archive');
-      expect(archiveContent).toContain('openspec archive <id> --skip-specs');
+      expect(archiveContent).toContain('openspec archive <id>');
+      expect(archiveContent).toContain('`--skip-specs` only for tooling-only work');
     });
 
     it('should create Cursor slash command files with templates', async () => {