lightspec 0.3.1 → 0.3.3

package/README.md

@@ -186,10 +186,10 @@ After `lightspec init` completes, you'll receive a suggested command to validate
 
 ```text
 Validate and populate your project context:
-"/lightspec:context-check"
+"/lightspec:agentsmd-check"
 ```
 
-Use the `/lightspec:context-check` skill to validate that your agent instruction file (CLAUDE.md or AGENTS.md) contains adequate project context. The skill will check for required properties like Purpose, Tech Stack, Architecture Patterns, and more. If anything is missing, it can help you explore the codebase and populate the missing information.
+Use the `/lightspec:agentsmd-check` skill to validate that your agent instruction file (CLAUDE.md or AGENTS.md) contains adequate project context. The skill will check for required properties like Purpose, Tech Stack, Architecture Patterns, and more. If anything is missing, it can help you explore the codebase and populate the missing information.
 
 ### Create Your First Change
 
@@ -399,10 +399,12 @@ See [MAINTAINERS.md](MAINTAINERS.md) for the list of core maintainers and adviso
 
 ## Agent Skills
 
-LightSpec includes 3 Claude Code skills for the core development workflow:
-- `lightspec-proposal` - Create a new change
-- `lightspec-apply` - Get apply instructions for implementation
-- `lightspec-archive` - Archive a completed change
+LightSpec includes 4 Claude Code skills for the core development workflow:
+
+- `lightspec:agentsmd-check` - Check the completeness of AGENTS.md or CLAUDE.md
+- `lightspec:proposal` - Create a new change
+- `lightspec:apply` - Get apply instructions for implementation
+- `lightspec:archive` - Archive a completed change
 
 See [README_SKILLS.md](README_SKILLS.md) for details.
 

package/dist/core/configurators/skills/base.js

@@ -3,7 +3,7 @@ import path from 'path';
 import { FileSystemUtils } from '../../../utils/file-system.js';
 import { TemplateManager } from '../../templates/index.js';
 import { LIGHTSPEC_MARKERS } from '../../config.js';
-const ALL_SKILL_IDS = ['proposal', 'apply', 'archive', 'context-check'];
+const ALL_SKILL_IDS = ['proposal', 'apply', 'archive', 'agentsmd-check'];
 const TOOL_SKILL_ROOTS = {
     'amazon-q': '.amazonq',
     antigravity: '.antigravity',

package/dist/core/init.js

@@ -615,7 +615,7 @@ export class InitCommand {
         console.log(`Next steps - Run these skills in ${toolName}:`);
         console.log(chalk.gray('────────────────────────────────────────────────────────────'));
         console.log(PALETTE.white('1. Validate and populate your project context:'));
-        console.log(PALETTE.lightGray('   "/lightspec:context-check"\n'));
+        console.log(PALETTE.lightGray('   "/lightspec:agentsmd-check"\n'));
         console.log(PALETTE.white('2. Create your first change proposal:'));
         console.log(PALETTE.lightGray('   "I want to add [YOUR FEATURE HERE]. Please create an'));
         console.log(PALETTE.lightGray('    LightSpec change proposal for this feature"\n'));

package/dist/core/templates/agent-skill-templates.d.ts

@@ -1,4 +1,4 @@
-export type AgentSkillId = 'proposal' | 'apply' | 'archive' | 'context-check';
+export type AgentSkillId = 'proposal' | 'apply' | 'archive' | 'agentsmd-check';
 export declare const agentSkillBodies: Record<AgentSkillId, string>;
 export declare const agentSkillFrontmatter: Record<AgentSkillId, string>;
 export declare function getAgentSkillBody(id: AgentSkillId): string;

package/dist/core/templates/agent-skill-templates.js

@@ -1,18 +1,18 @@
 import { applyTemplate, applyFrontmatter } from './apply-template.js';
 import { archiveTemplate, archiveFrontmatter } from './archive-template.js';
 import { proposalTemplate, proposalFrontmatter } from './proposal-template.js';
-import { contextCheckTemplate, contextCheckFrontmatter, } from './context-check-template.js';
+import { agentsmdCheckTemplate, agentsmdCheckFrontmatter, } from './agentsmd-check-template.js';
 export const agentSkillBodies = {
     proposal: proposalTemplate,
     apply: applyTemplate,
     archive: archiveTemplate,
-    'context-check': contextCheckTemplate,
+    'agentsmd-check': agentsmdCheckTemplate,
 };
 export const agentSkillFrontmatter = {
     proposal: proposalFrontmatter,
     apply: applyFrontmatter,
     archive: archiveFrontmatter,
-    'context-check': contextCheckFrontmatter,
+    'agentsmd-check': agentsmdCheckFrontmatter,
 };
 export function getAgentSkillBody(id) {
     return agentSkillBodies[id];

package/dist/core/templates/agents-root-stub.d.ts

@@ -1,2 +1,2 @@
-export declare const agentsRootStubTemplate = "# LightSpec Instructions\n\nThese instructions are for AI assistants working in this project.\n\n- For complex features (new capability, breaking change, architecture/performance/security work), suggest switching to `/plan` mode if it's not already the case, then run `lightspec-proposal` before coding.\n- If unsure which skill to run, list installed skills in your assistant's `skills/` folder.\n\nKeep this managed block so 'lightspec update' can refresh the instructions.\n";
+export declare const agentsRootStubTemplate = "# LightSpec Instructions\n\nThese instructions are for AI assistants working in this project.\n\n**If (and only if) the feature is complex** (new capability, breaking change, architecture/performance/security work), follow these steps:\n\n- [ ] Suggest switching to `/plan` mode before writing the proposal if it's not already the case\n- [ ] Run `lightspec-proposal`.\n- [ ] Do not implement the feature until the proposal is approved by the user. Implementation MUST be operated using `lightspec-apply` to ensure the implementation is properly tracked and documented.\n- [ ] If unsure which skill to run, list installed skills.\n\nKeep this managed block so 'lightspec update' can refresh the instructions.\n";
 //# sourceMappingURL=agents-root-stub.d.ts.map

package/dist/core/templates/agents-root-stub.js

@@ -2,8 +2,12 @@ export const agentsRootStubTemplate = `# LightSpec Instructions
 
 These instructions are for AI assistants working in this project.
 
-- For complex features (new capability, breaking change, architecture/performance/security work), suggest switching to \`/plan\` mode if it's not already the case, then run \`lightspec-proposal\` before coding.
-- If unsure which skill to run, list installed skills in your assistant's \`skills/\` folder.
+**If (and only if) the feature is complex** (new capability, breaking change, architecture/performance/security work), follow these steps:
+
+- [ ] Suggest switching to \`/plan\` mode before writing the proposal if it's not already the case
+- [ ] Run \`lightspec-proposal\`.
+- [ ] Do not implement the feature until the proposal is approved by the user. Implementation MUST be operated using \`lightspec-apply\` to ensure the implementation is properly tracked and documented.
+- [ ] If unsure which skill to run, list installed skills.
 
 Keep this managed block so 'lightspec update' can refresh the instructions.
 `;

package/dist/core/templates/agentsmd-check-template.d.ts

@@ -0,0 +1,3 @@
+export declare const agentsmdCheckFrontmatter = "---\nname: lightspec-agentsmd-check\ndescription: Validate project context in agent instruction files and help populate missing information.\ndisable-model-invocation: true\nuser-invocable: true\nmetadata:\n  source: lightspec\n  workflow: agentsmd-check\n---";
+export declare const agentsmdCheckTemplate = "**Goal**\nValidate that the project's agent instruction file (CLAUDE.md or AGENTS.md at project root) contains adequate context for AI assistants to work effectively with this codebase.\n\n**Detection Strategy**\nCheck which agent file exists by examining the context currently available to you (your \"memory\"). Do NOT read files from disk\u2014use only what has already been loaded into your context. If neither CLAUDE.md nor AGENTS.md appears to be in your current context, inform the user that no agent instruction file is currently loaded and suggest they open it in their editor or add it to the conversation.\n\n**Required Context Properties**\nThe agent file MUST contain these sections with meaningful, project-specific content:\n\n1. **Purpose** - Project goals and objectives (what the project does and why it exists)\n2. **Domain Context** - Domain-specific knowledge AI assistants need (business rules, terminology, concepts)\n3. **Tech Stack** - Technologies and frameworks used (languages, libraries, tools)\n4. **Project Non-Obvious Conventions** - Should include these subsections if applicable:\n   - Code Style (formatting rules, naming conventions)\n   - Architecture Patterns (architectural decisions and patterns)\n   - Testing Strategy (testing approach and requirements)\n   - Workflow Conventions (development workflow, branching strategy, CI/CD practices)\n5. **Important Constraints** - Technical, business, or regulatory constraints\n6. **External Dependencies** - Key external services, APIs, or systems\n\nThe agent file must be under 300 lines to maintain conciseness and focus on essential context.\n\n**Validation Criteria**\nFor each required property, classify as:\n- **Missing**: Section header absent or contains only placeholder text like `[...]`, `[Describe...]`, `[Add...]`, or `[List...]`\n- **Sub-optimal**: Section exists but is too brief (< 20 words) or generic/vague\n- **Good**: Section has meaningful, project-specific content (\u2265 20 words)\n\n**Validation Process**\n1. Identify which agent file is in your current context (CLAUDE.md or AGENTS.md)\n2. For each required property, check if it exists and classify its quality\n3. Report findings clearly:\n   - List properties that are **missing** or **sub-optimal**\n   - For each issue, explain what should be included\n   - Summarize which properties are **good**\n\n**Offering Exploration**\nIf any properties are missing or sub-optimal:\n1. Explain what needs improvement\n2. Ask: \"Would you like me to explore your codebase to gather this context and propose updates to [CLAUDE.md|AGENTS.md]?\"\n3. Wait for user confirmation before proceeding\n\n**If User Accepts Exploration**\n1. Systematically explore the codebase:\n   - **Tech Stack**: Check package.json, requirements.txt, go.mod, Cargo.toml, pom.xml, etc.\n   - **Architecture Patterns**: Examine project structure, folder organization, common code patterns, framework usage\n   - **Testing Strategy**: Look at test files, test frameworks (jest, pytest, etc.), test organization\n   - **Code Style**: Check for .prettierrc, .eslintrc, or other config files; examine actual code for conventions\n   - **Purpose**: Infer from README, package.json description, comments\n   - **Domain Context**: Identify from code comments, type definitions, business logic\n   - **Important Constraints**: Look for security patterns, performance considerations, compliance notes\n   - **External Dependencies**: Identify external API calls, third-party services, database connections\n2. Draft content for each missing/sub-optimal property\n3. Present the proposed content to the user for review\n4. Ask: \"Would you like me to write these additions to [CLAUDE.md|AGENTS.md]?\"\n5. Wait for confirmation before modifying the file\n\n**If User Declines Exploration**\nProvide manual guidance:\n- Explain what each missing/sub-optimal property should contain\n- Give examples of good content for each property\n- Suggest they populate the sections manually\n\n**Writing Confirmed Content**\nWhen user confirms:\n1. If the property section doesn't exist, add it\n2. If the property section exists but is sub-optimal, replace it with the improved content\n3. Preserve existing good content\u2014only update what needs improvement\n4. Use the Edit tool to make precise updates\n5. Confirm completion and show what was updated\n6. Suggest the user review the updated agent file and complement it with any additional details they think are important. Mention that additional documentation can be added to the docs/ folder in order to keep the agent file concise and focused on essential context for AI assistants.\n\n\n**Example Validation Report**\n```\n\u2713 Validated context in CLAUDE.md\n\nMissing properties (3):\n- Purpose: Should describe project goals and what it does\n- Domain Context: Should include business rules, terminology, concepts\n- Important Constraints: Should list technical, business, or regulatory constraints\n\nSub-optimal properties (2):\n- Tech Stack: Only 8 words - needs more detail about frameworks and tools\n- Code Style: Generic description - needs project-specific conventions\n\nGood properties (2):\n- Architecture Patterns: Well-documented with clear explanations\n- Testing Strategy: Comprehensive with examples\n\nWould you like me to explore your codebase to gather this context and propose updates to CLAUDE.md?\n```\n\n**Important Notes**\n\n***When checking context:***\n\n- The check must address exclusively the agent file currently in your context\u2014do NOT read files from disk\n- Never modify files without explicit user confirmation\n- Present all proposed content for review before writing\n- Focus on project-specific details, not generic advice\n- Keep tone helpful and educational\n\n***When writing or updating the agent file:***\n\n- Only add or update sections that are missing or sub-optimal\u2014do NOT alter sections that are already good\n- Preserve any existing meaningful content in the file\n- Use clear, concise language with project-specific details\n- Confirm with the user before making any changes to the file\n- Focus your edits exclusively on the invariant properties of the codebase\n- Do not focus on transient details that may change frequently. For instance:\n   - Ignore component-level implementation details\n   - Ignore specific function signatures or variable names\n   - Ignore comments that are not relevant to the overall project context\n- Ignore files inside the agent folders (often named .<agent_name>)\n- Prefer concise bullet points instead of extensive prose\n- Keep the final document under 300 lines to ensure it remains concise and focused on essential context for AI assistants\n- After writing, summarize what was updated and confirm completion";
+//# sourceMappingURL=agentsmd-check-template.d.ts.map

package/dist/core/templates/{context-check-template.js → agentsmd-check-template.js}

@@ -1,13 +1,13 @@
-export const contextCheckFrontmatter = `---
-name: lightspec-context-check
+export const agentsmdCheckFrontmatter = `---
+name: lightspec-agentsmd-check
 description: Validate project context in agent instruction files and help populate missing information.
 disable-model-invocation: true
 user-invocable: true
 metadata:
   source: lightspec
-  workflow: context-check
+  workflow: agentsmd-check
 ---`;
-export const contextCheckTemplate = `**Goal**
+export const agentsmdCheckTemplate = `**Goal**
 Validate that the project's agent instruction file (CLAUDE.md or AGENTS.md at project root) contains adequate context for AI assistants to work effectively with this codebase.
 
 **Detection Strategy**
@@ -125,4 +125,4 @@ Would you like me to explore your codebase to gather this context and propose up
 - Prefer concise bullet points instead of extensive prose
 - Keep the final document under 300 lines to ensure it remains concise and focused on essential context for AI assistants
 - After writing, summarize what was updated and confirm completion`;
-//# sourceMappingURL=context-check-template.js.map
+//# sourceMappingURL=agentsmd-check-template.js.map

package/dist/core/templates/proposal-template.js

@@ -11,17 +11,19 @@ metadata:
 const proposalGuardrails = `${baseGuardrails}\n- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
 - Do not write any code during the proposal stage. Only create design documents (proposal.md, tasks.md, design.md, and spec deltas). Implementation happens in the apply stage after approval.`;
 const proposalSteps = `**Steps**
-1. Run \`lightspec list\` and \`lightspec 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 \`lightspec/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/<capability>/spec.md\` (one folder per capability) 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 \`lightspec validate <id> --strict --no-interactive\` and resolve every issue before sharing the proposal.`;
+1. Run \`lightspec list\` and \`lightspec list --specs\`, and inspect related code or docs (e.g., via \`rg\`/\`ls\`) to ground the proposal in current behaviour.
+2. Note any gaps in the user plan that require clarification. Ask follow-up questions to resolve ambiguities before proceeding. Avoid making assumptions about unstated requirements or implementation details.
+3. Choose a unique verb-led \`change-id\` and scaffold \`proposal.md\`, \`tasks.md\`, and \`design.md\` (when needed) under \`lightspec/changes/<id>/\`.
+4. Map the change into concrete capabilities or requirements, breaking multi-scope efforts into distinct spec deltas with clear relationships and sequencing.
+5. Capture architectural reasoning in \`design.md\` when the solution spans multiple systems, introduces new patterns, or demands trade-off discussion before committing to specs.
+6. Draft spec deltas in \`changes/<id>/specs/<capability>/spec.md\` (one folder per capability) using \`## ADDED|MODIFIED|REMOVED Requirements\` with at least one \`#### Scenario:\` per requirement and cross-reference related capabilities when relevant.
+7. 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.
+8. Validate with \`lightspec validate <id> --strict --no-interactive\` and resolve every issue before sharing the proposal.`;
 const proposalReferences = `**Reference**
 - Use \`lightspec show <id> --json --deltas-only\` or \`lightspec show <spec> --type spec\` to inspect details when validation fails.
 - Search existing requirements with \`rg -n "Requirement:|Scenario:" lightspec/specs\` before writing new ones.
-- Explore the codebase with \`rg <keyword>\`, \`ls\`, or direct file reads so proposals align with current implementation realities.`;
+- Explore the codebase with \`rg <keyword>\`, \`ls\`, or direct file reads so proposals align with current implementation realities.
+- If rg is unavailable, use platform-native search tools and suggest installing rg for efficient proposal development.`;
 export const proposalTemplate = [
     proposalGuardrails,
     proposalSteps,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightspec",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "lightspec",

package/dist/core/templates/context-check-template.d.ts

@@ -1,3 +0,0 @@
-export declare const contextCheckFrontmatter = "---\nname: lightspec-context-check\ndescription: Validate project context in agent instruction files and help populate missing information.\ndisable-model-invocation: true\nuser-invocable: true\nmetadata:\n  source: lightspec\n  workflow: context-check\n---";
-export declare const contextCheckTemplate = "**Goal**\nValidate that the project's agent instruction file (CLAUDE.md or AGENTS.md at project root) contains adequate context for AI assistants to work effectively with this codebase.\n\n**Detection Strategy**\nCheck which agent file exists by examining the context currently available to you (your \"memory\"). Do NOT read files from disk\u2014use only what has already been loaded into your context. If neither CLAUDE.md nor AGENTS.md appears to be in your current context, inform the user that no agent instruction file is currently loaded and suggest they open it in their editor or add it to the conversation.\n\n**Required Context Properties**\nThe agent file MUST contain these sections with meaningful, project-specific content:\n\n1. **Purpose** - Project goals and objectives (what the project does and why it exists)\n2. **Domain Context** - Domain-specific knowledge AI assistants need (business rules, terminology, concepts)\n3. **Tech Stack** - Technologies and frameworks used (languages, libraries, tools)\n4. **Project Non-Obvious Conventions** - Should include these subsections if applicable:\n   - Code Style (formatting rules, naming conventions)\n   - Architecture Patterns (architectural decisions and patterns)\n   - Testing Strategy (testing approach and requirements)\n   - Workflow Conventions (development workflow, branching strategy, CI/CD practices)\n5. **Important Constraints** - Technical, business, or regulatory constraints\n6. **External Dependencies** - Key external services, APIs, or systems\n\nThe agent file must be under 300 lines to maintain conciseness and focus on essential context.\n\n**Validation Criteria**\nFor each required property, classify as:\n- **Missing**: Section header absent or contains only placeholder text like `[...]`, `[Describe...]`, `[Add...]`, or `[List...]`\n- **Sub-optimal**: Section exists but is too brief (< 20 words) or generic/vague\n- **Good**: Section has meaningful, project-specific content (\u2265 20 words)\n\n**Validation Process**\n1. Identify which agent file is in your current context (CLAUDE.md or AGENTS.md)\n2. For each required property, check if it exists and classify its quality\n3. Report findings clearly:\n   - List properties that are **missing** or **sub-optimal**\n   - For each issue, explain what should be included\n   - Summarize which properties are **good**\n\n**Offering Exploration**\nIf any properties are missing or sub-optimal:\n1. Explain what needs improvement\n2. Ask: \"Would you like me to explore your codebase to gather this context and propose updates to [CLAUDE.md|AGENTS.md]?\"\n3. Wait for user confirmation before proceeding\n\n**If User Accepts Exploration**\n1. Systematically explore the codebase:\n   - **Tech Stack**: Check package.json, requirements.txt, go.mod, Cargo.toml, pom.xml, etc.\n   - **Architecture Patterns**: Examine project structure, folder organization, common code patterns, framework usage\n   - **Testing Strategy**: Look at test files, test frameworks (jest, pytest, etc.), test organization\n   - **Code Style**: Check for .prettierrc, .eslintrc, or other config files; examine actual code for conventions\n   - **Purpose**: Infer from README, package.json description, comments\n   - **Domain Context**: Identify from code comments, type definitions, business logic\n   - **Important Constraints**: Look for security patterns, performance considerations, compliance notes\n   - **External Dependencies**: Identify external API calls, third-party services, database connections\n2. Draft content for each missing/sub-optimal property\n3. Present the proposed content to the user for review\n4. Ask: \"Would you like me to write these additions to [CLAUDE.md|AGENTS.md]?\"\n5. Wait for confirmation before modifying the file\n\n**If User Declines Exploration**\nProvide manual guidance:\n- Explain what each missing/sub-optimal property should contain\n- Give examples of good content for each property\n- Suggest they populate the sections manually\n\n**Writing Confirmed Content**\nWhen user confirms:\n1. If the property section doesn't exist, add it\n2. If the property section exists but is sub-optimal, replace it with the improved content\n3. Preserve existing good content\u2014only update what needs improvement\n4. Use the Edit tool to make precise updates\n5. Confirm completion and show what was updated\n6. Suggest the user review the updated agent file and complement it with any additional details they think are important. Mention that additional documentation can be added to the docs/ folder in order to keep the agent file concise and focused on essential context for AI assistants.\n\n\n**Example Validation Report**\n```\n\u2713 Validated context in CLAUDE.md\n\nMissing properties (3):\n- Purpose: Should describe project goals and what it does\n- Domain Context: Should include business rules, terminology, concepts\n- Important Constraints: Should list technical, business, or regulatory constraints\n\nSub-optimal properties (2):\n- Tech Stack: Only 8 words - needs more detail about frameworks and tools\n- Code Style: Generic description - needs project-specific conventions\n\nGood properties (2):\n- Architecture Patterns: Well-documented with clear explanations\n- Testing Strategy: Comprehensive with examples\n\nWould you like me to explore your codebase to gather this context and propose updates to CLAUDE.md?\n```\n\n**Important Notes**\n\n***When checking context:***\n\n- The check must address exclusively the agent file currently in your context\u2014do NOT read files from disk\n- Never modify files without explicit user confirmation\n- Present all proposed content for review before writing\n- Focus on project-specific details, not generic advice\n- Keep tone helpful and educational\n\n***When writing or updating the agent file:***\n\n- Only add or update sections that are missing or sub-optimal\u2014do NOT alter sections that are already good\n- Preserve any existing meaningful content in the file\n- Use clear, concise language with project-specific details\n- Confirm with the user before making any changes to the file\n- Focus your edits exclusively on the invariant properties of the codebase\n- Do not focus on transient details that may change frequently. For instance:\n   - Ignore component-level implementation details\n   - Ignore specific function signatures or variable names\n   - Ignore comments that are not relevant to the overall project context\n- Ignore files inside the agent folders (often named .<agent_name>)\n- Prefer concise bullet points instead of extensive prose\n- Keep the final document under 300 lines to ensure it remains concise and focused on essential context for AI assistants\n- After writing, summarize what was updated and confirm completion";
-//# sourceMappingURL=context-check-template.d.ts.map