@ias-ai/zhima-spec 1.3.1

package/dist/utils/item-discovery.js

@@ -0,0 +1,72 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+export async function getActiveChangeIds(root = process.cwd()) {
+    const changesPath = path.join(root, 'zhima', 'changes');
+    try {
+        const entries = await fs.readdir(changesPath, { withFileTypes: true });
+        const result = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'archive')
+                continue;
+            const proposalPath = path.join(changesPath, entry.name, 'proposal.md');
+            try {
+                await fs.access(proposalPath);
+                result.push(entry.name);
+            }
+            catch {
+                // skip directories without proposal.md
+            }
+        }
+        return result.sort();
+    }
+    catch {
+        return [];
+    }
+}
+export async function getSpecIds(root = process.cwd()) {
+    const specsPath = path.join(root, 'zhima', 'specs');
+    const result = [];
+    try {
+        const entries = await fs.readdir(specsPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            const specFile = path.join(specsPath, entry.name, 'spec.md');
+            try {
+                await fs.access(specFile);
+                result.push(entry.name);
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    return result.sort();
+}
+export async function getArchivedChangeIds(root = process.cwd()) {
+    const archivePath = path.join(root, 'zhima', 'changes', 'archive');
+    try {
+        const entries = await fs.readdir(archivePath, { withFileTypes: true });
+        const result = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            const proposalPath = path.join(archivePath, entry.name, 'proposal.md');
+            try {
+                await fs.access(proposalPath);
+                result.push(entry.name);
+            }
+            catch {
+                // skip directories without proposal.md
+            }
+        }
+        return result.sort();
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=item-discovery.js.map

package/dist/utils/match.d.ts

@@ -0,0 +1,3 @@
+export declare function nearestMatches(input: string, candidates: string[], max?: number): string[];
+export declare function levenshtein(a: string, b: string): number;
+//# sourceMappingURL=match.d.ts.map

package/dist/utils/match.js

@@ -0,0 +1,22 @@
+export function nearestMatches(input, candidates, max = 5) {
+    const scored = candidates.map(candidate => ({ candidate, distance: levenshtein(input, candidate) }));
+    scored.sort((a, b) => a.distance - b.distance);
+    return scored.slice(0, max).map(s => s.candidate);
+}
+export function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + cost);
+        }
+    }
+    return dp[m][n];
+}
+//# sourceMappingURL=match.js.map

package/dist/utils/shell-detection.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Supported shell types for completion generation
+ */
+export type SupportedShell = 'zsh' | 'bash' | 'fish' | 'powershell';
+/**
+ * Result of shell detection
+ */
+export interface ShellDetectionResult {
+    /** The detected shell if supported, otherwise undefined */
+    shell: SupportedShell | undefined;
+    /** The raw shell name detected (even if unsupported), or undefined if nothing detected */
+    detected: string | undefined;
+}
+/**
+ * Detects the current user's shell based on environment variables
+ *
+ * @returns Detection result with supported shell and raw detected name
+ */
+export declare function detectShell(): ShellDetectionResult;
+//# sourceMappingURL=shell-detection.d.ts.map

package/dist/utils/shell-detection.js

@@ -0,0 +1,41 @@
+/**
+ * Detects the current user's shell based on environment variables
+ *
+ * @returns Detection result with supported shell and raw detected name
+ */
+export function detectShell() {
+    // Try SHELL environment variable first (Unix-like systems)
+    const shellPath = process.env.SHELL;
+    if (shellPath) {
+        const shellName = shellPath.toLowerCase();
+        if (shellName.includes('zsh')) {
+            return { shell: 'zsh', detected: 'zsh' };
+        }
+        if (shellName.includes('bash')) {
+            return { shell: 'bash', detected: 'bash' };
+        }
+        if (shellName.includes('fish')) {
+            return { shell: 'fish', detected: 'fish' };
+        }
+        // Shell detected but not supported
+        // Extract shell name from path (e.g., /bin/tcsh -> tcsh)
+        const match = shellPath.match(/\/([^/]+)$/);
+        const detectedName = match ? match[1] : shellPath;
+        return { shell: undefined, detected: detectedName };
+    }
+    // Check for PowerShell on Windows
+    // PSModulePath is a reliable PowerShell-specific environment variable
+    if (process.env.PSModulePath || process.platform === 'win32') {
+        const comspec = process.env.COMSPEC?.toLowerCase();
+        // If PSModulePath exists, we're definitely in PowerShell
+        if (process.env.PSModulePath) {
+            return { shell: 'powershell', detected: 'powershell' };
+        }
+        // On Windows without PSModulePath, we might be in cmd.exe
+        if (comspec?.includes('cmd.exe')) {
+            return { shell: undefined, detected: 'cmd.exe' };
+        }
+    }
+    return { shell: undefined, detected: undefined };
+}
+//# sourceMappingURL=shell-detection.js.map

package/dist/utils/task-progress.d.ts

@@ -0,0 +1,8 @@
+export interface TaskProgress {
+    total: number;
+    completed: number;
+}
+export declare function countTasksFromContent(content: string): TaskProgress;
+export declare function getTaskProgressForChange(changesDir: string, changeName: string): Promise<TaskProgress>;
+export declare function formatTaskStatus(progress: TaskProgress): string;
+//# sourceMappingURL=task-progress.d.ts.map

package/dist/utils/task-progress.js

@@ -0,0 +1,36 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+const TASK_PATTERN = /^[-*]\s+\[[\sx]\]/i;
+const COMPLETED_TASK_PATTERN = /^[-*]\s+\[x\]/i;
+export function countTasksFromContent(content) {
+    const lines = content.split('\n');
+    let total = 0;
+    let completed = 0;
+    for (const line of lines) {
+        if (line.match(TASK_PATTERN)) {
+            total++;
+            if (line.match(COMPLETED_TASK_PATTERN)) {
+                completed++;
+            }
+        }
+    }
+    return { total, completed };
+}
+export async function getTaskProgressForChange(changesDir, changeName) {
+    const tasksPath = path.join(changesDir, changeName, 'tasks.md');
+    try {
+        const content = await fs.readFile(tasksPath, 'utf-8');
+        return countTasksFromContent(content);
+    }
+    catch {
+        return { total: 0, completed: 0 };
+    }
+}
+export function formatTaskStatus(progress) {
+    if (progress.total === 0)
+        return 'No tasks';
+    if (progress.completed === progress.total)
+        return '✓ Complete';
+    return `${progress.completed}/${progress.total} tasks`;
+}
+//# sourceMappingURL=task-progress.js.map

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@ias-ai/zhima-spec",
+  "version": "1.3.1",
+  "description": "AI-native system development flow",
+  "keywords": [
+    "zhima",
+    "specs",
+    "cli",
+    "ai",
+    "development"
+  ],
+  "homepage": "https://gitlab.oneberry.cc:2083/zhima-agent/ias-workflow",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.oneberry.cc:2083/zhima-agent/ias-workflow"
+  },
+  "license": "MIT",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "zhima": "./bin/zhima.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "schemas",
+    "scripts/postinstall.js",
+    "!dist/**/*.test.js",
+    "!dist/**/__tests__",
+    "!dist/**/*.map"
+  ],
+  "scripts": {
+    "lint": "eslint src/",
+    "build": "node build.js",
+    "dev": "tsc --watch",
+    "dev:cli": "pnpm build && node bin/zhima.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "test:postinstall": "node scripts/postinstall.js",
+    "prepare": "pnpm run build",
+    "prepublishOnly": "pnpm run build",
+    "postinstall": "node scripts/postinstall.js",
+    "check:pack-version": "node scripts/pack-version-check.mjs",
+    "release": "pnpm run release:ci",
+    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
+    "changeset": "changeset"
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^0.5.2",
+    "@changesets/cli": "^2.27.7",
+    "@types/node": "^24.2.0",
+    "@vitest/ui": "^3.2.4",
+    "eslint": "^9.39.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.1",
+    "vitest": "^3.2.4"
+  },
+  "dependencies": {
+    "@inquirer/core": "^10.2.2",
+    "@inquirer/prompts": "^7.8.0",
+    "chalk": "^5.5.0",
+    "commander": "^14.0.0",
+    "cross-spawn": "7.0.6",
+    "fast-glob": "^3.3.3",
+    "ora": "^8.2.0",
+    "yaml": "^2.8.2",
+    "zod": "^4.0.17"
+  }
+}

package/schemas/spec-driven/schema.yaml

@@ -0,0 +1,153 @@
+name: spec-driven
+version: 1
+description: Default ZhiMa workflow - proposal → specs → design → tasks
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Initial proposal document outlining the change
+    template: proposal.md
+    instruction: |
+      Create the proposal document that establishes WHY this change is needed.
+
+      Sections:
+      - **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
+      - **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
+      - **Capabilities**: Identify which specs will be created or modified:
+        - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<name>/spec.md`. Use kebab-case names (e.g., `user-auth`, `data-export`).
+        - **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Check `zhima/specs/` for existing spec names. Leave empty if no requirement changes.
+      - **Impact**: Affected code, APIs, dependencies, or systems.
+
+      IMPORTANT: The Capabilities section is critical. It creates the contract between
+      proposal and specs phases. Research existing specs before filling this in.
+      Each capability listed here will need a corresponding spec file.
+
+      Keep it concise (1-2 pages). Focus on the "why" not the "how" -
+      implementation details belong in design.md.
+
+      This is the foundation - specs, design, and tasks all build on this.
+    requires: []
+
+  - id: specs
+    generates: "specs/**/*.md"
+    description: Detailed specifications for the change
+    template: spec.md
+    instruction: |
+      Create specification files that define WHAT the system should do.
+
+      Create one spec file per capability listed in the proposal's Capabilities section.
+      - New capabilities: use the exact kebab-case name from the proposal (specs/<capability>/spec.md).
+      - Modified capabilities: use the existing spec folder name from zhima/specs/<capability>/ when creating the delta spec at specs/<capability>/spec.md.
+
+      Delta operations (use ## headers):
+      - **ADDED Requirements**: New capabilities
+      - **MODIFIED Requirements**: Changed behavior - MUST include full updated content
+      - **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration**
+      - **RENAMED Requirements**: Name changes only - use FROM:/TO: format
+
+      Format requirements:
+      - Each requirement: `### Requirement: <name>` followed by description
+      - Use SHALL/MUST for normative requirements (avoid should/may)
+      - Each scenario: `#### Scenario: <name>` with WHEN/THEN format
+      - **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
+      - Every requirement MUST have at least one scenario.
+
+      MODIFIED requirements workflow:
+      1. Locate the existing requirement in zhima/specs/<capability>/spec.md
+      2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
+      3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
+      4. Ensure header text matches exactly (whitespace-insensitive)
+
+      Common pitfall: Using MODIFIED with partial content loses detail at archive time.
+      If adding new concerns without changing existing behavior, use ADDED instead.
+
+      Example:
+      ```
+      ## ADDED Requirements
+
+      ### Requirement: User can export data
+      The system SHALL allow users to export their data in CSV format.
+
+      #### Scenario: Successful export
+      - **WHEN** user clicks "Export" button
+      - **THEN** system downloads a CSV file with all user data
+
+      ## REMOVED Requirements
+
+      ### Requirement: Legacy export
+      **Reason**: Replaced by new export system
+      **Migration**: Use new export endpoint at /api/v2/export
+      ```
+
+      Specs should be testable - each scenario is a potential test case.
+    requires:
+      - proposal
+
+  - id: design
+    generates: design.md
+    description: Technical design document with implementation details
+    template: design.md
+    instruction: |
+      Create the design document that explains HOW to implement the change.
+
+      When to include design.md (create only if any apply):
+      - Cross-cutting change (multiple services/modules) or new architectural pattern
+      - New external dependency or significant data model changes
+      - Security, performance, or migration complexity
+      - Ambiguity that benefits from technical decisions before coding
+
+      Sections:
+      - **Context**: Background, current state, constraints, stakeholders
+      - **Goals / Non-Goals**: What this design achieves and explicitly excludes
+      - **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision.
+      - **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation
+      - **Migration Plan**: Steps to deploy, rollback strategy (if applicable)
+      - **Open Questions**: Outstanding decisions or unknowns to resolve
+
+      Focus on architecture and approach, not line-by-line implementation.
+      Reference the proposal for motivation and specs for requirements.
+
+      Good design docs explain the "why" behind technical decisions.
+    requires:
+      - proposal
+
+  - id: tasks
+    generates: tasks.md
+    description: Implementation checklist with trackable tasks
+    template: tasks.md
+    instruction: |
+      Create the task list that breaks down the implementation work.
+
+      **IMPORTANT: Follow the template below exactly.** The apply phase parses
+      checkbox format to track progress. Tasks not using `- [ ]` won't be tracked.
+
+      Guidelines:
+      - Group related tasks under ## numbered headings
+      - Each task MUST be a checkbox: `- [ ] X.Y Task description`
+      - Tasks should be small enough to complete in one session
+      - Order tasks by dependency (what must be done first?)
+
+      Example:
+      ```
+      ## 1. Setup
+
+      - [ ] 1.1 Create new module structure
+      - [ ] 1.2 Add dependencies to package.json
+
+      ## 2. Core Implementation
+
+      - [ ] 2.1 Implement data export function
+      - [ ] 2.2 Add CSV formatting utilities
+      ```
+
+      Reference specs for what needs to be built, design for how to build it.
+      Each task should be verifiable - you know when it's done.
+    requires:
+      - specs
+      - design
+
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  instruction: |
+    Read context files, work through pending tasks, mark complete as you go.
+    Pause if you hit blockers or need clarification.

package/schemas/spec-driven/templates/design.md

@@ -0,0 +1,19 @@
+## Context
+
+<!-- Background and current state -->
+
+## Goals / Non-Goals
+
+**Goals:**
+<!-- What this design aims to achieve -->
+
+**Non-Goals:**
+<!-- What is explicitly out of scope -->
+
+## Decisions
+
+<!-- Key design decisions and rationale -->
+
+## Risks / Trade-offs
+
+<!-- Known risks and trade-offs -->

package/schemas/spec-driven/templates/proposal.md

@@ -0,0 +1,23 @@
+## Why
+
+<!-- Explain the motivation for this change. What problem does this solve? Why now? -->
+
+## What Changes
+
+<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->
+
+## Capabilities
+
+### New Capabilities
+<!-- Capabilities being introduced. Replace <name> with kebab-case identifier (e.g., user-auth, data-export, api-rate-limiting). Each creates specs/<name>/spec.md -->
+- `<name>`: <brief description of what this capability covers>
+
+### Modified Capabilities
+<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
+     Only list here if spec-level behavior changes. Each needs a delta spec file.
+     Use existing spec names from zhima/specs/. Leave empty if no requirement changes. -->
+- `<existing-name>`: <what requirement is changing>
+
+## Impact
+
+<!-- Affected code, APIs, dependencies, systems -->

package/schemas/spec-driven/templates/spec.md

@@ -0,0 +1,8 @@
+## ADDED Requirements
+
+### Requirement: <!-- requirement name -->
+<!-- requirement text -->
+
+#### Scenario: <!-- scenario name -->
+- **WHEN** <!-- condition -->
+- **THEN** <!-- expected outcome -->

package/schemas/spec-driven/templates/tasks.md

@@ -0,0 +1,9 @@
+## 1. <!-- Task Group Name -->
+
+- [ ] 1.1 <!-- Task description -->
+- [ ] 1.2 <!-- Task description -->
+
+## 2. <!-- Task Group Name -->
+
+- [ ] 2.1 <!-- Task description -->
+- [ ] 2.2 <!-- Task description -->

package/schemas/workspace-planning/schema.yaml

@@ -0,0 +1,72 @@
+name: workspace-planning
+version: 1
+description: Workspace planning workflow for cross-area changes
+artifacts:
+  - id: proposal
+    generates: proposal.md
+    description: Shared workspace proposal with the product goal, scope, affected areas, and impact
+    template: proposal.md
+    instruction: |
+      Create the workspace-level proposal that captures the shared product goal once.
+
+      Sections:
+      - **Why**: Explain the product goal or problem in 1-2 concise paragraphs.
+      - **What Changes**: List the cross-area behavior, workflow, or capability changes.
+      - **Affected Areas**: Name known affected areas using registered workspace link names where applicable. If scope is still being explored, say what remains unresolved.
+      - **Capabilities**: Identify workspace-scoped capabilities that need specs. Area-specific requirements should later live under `specs/<area-or-repo>/<capability>/spec.md`.
+      - **Impact**: Summarize user-facing impact, planning impact, and likely implementation homes without creating repo-local artifacts.
+
+      Keep linked repos and folders as exploration context until an explicit implementation workflow selects an affected area.
+    requires: []
+
+  - id: specs
+    generates: "specs/**/*.md"
+    description: Workspace-scoped specs organized by affected area and capability
+    template: spec.md
+    instruction: |
+      Create workspace-scoped specification files that define WHAT should change.
+
+      Use `specs/<area-or-repo>/<capability>/spec.md` for area-specific requirements. The first path segment should be a registered workspace link name when a registered area owns the requirement. If the area is unresolved, use an exploratory area name and make the unresolved question explicit in the requirement or scenario.
+
+      These specs are planning artifacts under the workspace change root. Do not create repo-local spec files in linked repos during workspace planning.
+
+      Delta operations (use ## headers):
+      - **ADDED Requirements**: New workspace-scoped behavior.
+      - **MODIFIED Requirements**: Changed behavior; include the full updated requirement.
+      - **REMOVED Requirements**: Deprecated behavior with Reason and Migration.
+      - **RENAMED Requirements**: Name changes only; use FROM:/TO: format.
+
+      Each requirement must use SHALL/MUST language and include at least one `#### Scenario:` block.
+    requires:
+      - proposal
+
+  - id: design
+    generates: design.md
+    description: Cross-area technical design and coordination decisions
+    template: design.md
+    instruction: |
+      Create the cross-area design document for workspace planning.
+
+      Focus on decisions that affect multiple areas, handoffs between areas, shared constraints, sequencing risks, and how the workspace plan should stay the source of truth. Avoid line-by-line implementation details and do not instruct agents to edit linked repos until an explicit implementation workflow provides an allowed edit root.
+    requires:
+      - proposal
+
+  - id: tasks
+    generates: tasks.md
+    description: Coordination checklist for workspace planning and later affected-area implementation
+    template: tasks.md
+    instruction: |
+      Create the workspace coordination task list.
+
+      Group tasks by phase or affected area as useful. Each actionable item must be a checkbox using `- [ ]`. When implementation tasks are area-specific, name the affected area and keep the task at planning granularity until a later implementation workflow selects an allowed edit root.
+    requires:
+      - specs
+      - design
+
+apply:
+  requires: [tasks]
+  tracks: tasks.md
+  instruction: |
+    Read the workspace planning context from status and instructions output before applying.
+    Select an affected area and confirm an allowed edit root before making implementation edits.
+    Until an explicit implementation context is available, treat linked repos and folders as read-only exploration context.

package/schemas/workspace-planning/templates/design.md

@@ -0,0 +1,33 @@
+## Context
+
+Summarize the workspace planning context, relevant linked areas, and constraints.
+
+## Goals / Non-Goals
+
+**Goals:**
+-
+
+**Non-Goals:**
+- Creating repo-local implementation artifacts before an affected area is selected.
+
+## Decisions
+
+### Decision: <title>
+
+<decision and rationale>
+
+Alternative considered: <alternative and why it was not chosen>
+
+## Risks / Trade-offs
+
+- <risk> -> <mitigation>
+
+## Coordination Notes
+
+- Affected areas:
+- Open handoffs:
+- Implementation entry criteria:
+
+## Open Questions
+
+-

package/schemas/workspace-planning/templates/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+Describe the shared product goal, problem, or opportunity that makes this workspace-level change worth planning.
+
+## What Changes
+
+-
+
+## Affected Areas
+
+- Known:
+- Unresolved:
+
+## Capabilities
+
+### New Capabilities
+
+-
+
+### Modified Capabilities
+
+-
+
+## Impact
+
+- Workspace planning:
+- Linked repos or folders:
+- User-facing behavior:

package/schemas/workspace-planning/templates/spec.md

@@ -0,0 +1,9 @@
+## ADDED Requirements
+
+### Requirement: <workspace requirement name>
+The workspace plan SHALL describe the required behavior and affected area without creating repo-local artifacts during planning.
+
+#### Scenario: <scenario name>
+- **GIVEN** <context>
+- **WHEN** <action>
+- **THEN** <observable result>

package/schemas/workspace-planning/templates/tasks.md

@@ -0,0 +1,15 @@
+## 1. Workspace Planning
+
+- [ ] 1.1 Confirm the shared product goal and unresolved scope questions.
+- [ ] 1.2 Identify affected areas using registered workspace link names where applicable.
+- [ ] 1.3 Review workspace-scoped specs and design before selecting implementation areas.
+
+## 2. Affected Area Implementation
+
+- [ ] 2.1 Select an affected area and confirm its allowed edit root before implementation.
+- [ ] 2.2 Create or update repo-local implementation artifacts only after the area is selected.
+
+## 3. Verification
+
+- [ ] 3.1 Verify workspace planning artifacts remain the source of truth.
+- [ ] 3.2 Record manual acceptance evidence and follow-up fixes.