@shahmarasy/prodo 0.1.3 → 0.1.5

package/src/skills/engine.ts

@@ -0,0 +1,94 @@
+import { UserError } from "../core/errors";
+import type { Skill, SkillContext, SkillManifest } from "./types";
+
+export type SkillEngine = {
+  register(skill: Skill): void;
+  getSkill(name: string): Skill | undefined;
+  listSkills(): SkillManifest[];
+  execute(name: string, context: SkillContext, inputs: Record<string, unknown>): Promise<Record<string, unknown>>;
+};
+
+function validateInputs(skill: Skill, inputs: Record<string, unknown>): void {
+  for (const input of skill.manifest.inputs) {
+    if (input.required && !(input.name in inputs)) {
+      throw new UserError(
+        `Skill "${skill.manifest.name}" requires input "${input.name}" (${input.description})`
+      );
+    }
+  }
+}
+
+export function createSkillEngine(): SkillEngine {
+  const skills = new Map<string, Skill>();
+
+  return {
+    register(skill: Skill): void {
+      skills.set(skill.manifest.name, skill);
+    },
+
+    getSkill(name: string): Skill | undefined {
+      return skills.get(name);
+    },
+
+    listSkills(): SkillManifest[] {
+      return Array.from(skills.values()).map((s) => s.manifest);
+    },
+
+    async execute(
+      name: string,
+      context: SkillContext,
+      inputs: Record<string, unknown>
+    ): Promise<Record<string, unknown>> {
+      const skill = skills.get(name);
+      if (!skill) {
+        const available = Array.from(skills.keys()).join(", ");
+        throw new UserError(`Unknown skill: "${name}". Available: ${available}`);
+      }
+
+      validateInputs(skill, inputs);
+      return skill.execute(context, inputs);
+    }
+  };
+}
+
+let globalEngine: SkillEngine | null = null;
+
+export function getGlobalSkillEngine(): SkillEngine {
+  if (!globalEngine) {
+    globalEngine = createSkillEngine();
+    loadBuiltinSkills(globalEngine);
+  }
+  return globalEngine;
+}
+
+export function resetGlobalSkillEngine(): void {
+  globalEngine = null;
+}
+
+function loadBuiltinSkills(engine: SkillEngine): void {
+  // Lazy-load to avoid circular dependencies
+  try {
+    const { normalizeSkill } = require("./normalize-skill") as { normalizeSkill: Skill };
+    engine.register(normalizeSkill);
+  } catch { /* skill not available */ }
+
+  try {
+    const { validateSkill } = require("./validate-skill") as { validateSkill: Skill };
+    engine.register(validateSkill);
+  } catch { /* skill not available */ }
+
+  try {
+    const { fixSkill } = require("./fix-skill") as { fixSkill: Skill };
+    engine.register(fixSkill);
+  } catch { /* skill not available */ }
+
+  try {
+    const { generateArtifactSkill } = require("./generate-artifact-skill") as { generateArtifactSkill: Skill };
+    engine.register(generateArtifactSkill);
+  } catch { /* skill not available */ }
+
+  try {
+    const { generatePipelineSkill } = require("./generate-pipeline-skill") as { generatePipelineSkill: Skill };
+    engine.register(generatePipelineSkill);
+  } catch { /* skill not available */ }
+}

package/src/skills/fix-skill.ts

@@ -0,0 +1,38 @@
+import { runFix } from "../core/fix";
+import type { Skill } from "./types";
+
+export const fixSkill: Skill = {
+  manifest: {
+    name: "fix",
+    description: "Auto-regenerate artifacts that failed validation with backup and rollback",
+    category: "validation",
+    inputs: [
+      { name: "cwd", type: "path", required: true, description: "Project working directory" },
+      { name: "agent", type: "string", required: false, description: "Agent profile name" },
+      { name: "strict", type: "boolean", required: false, description: "Treat warnings as errors" },
+      { name: "dryRun", type: "boolean", required: false, description: "Preview without applying" }
+    ],
+    outputs: [
+      { name: "applied", type: "string", description: "Whether fix was applied" },
+      { name: "finalPass", type: "string", description: "Whether validation passed after fix" },
+      { name: "reportPath", type: "path", description: "Path to validation report" }
+    ]
+  },
+
+  async execute(context, inputs): Promise<Record<string, unknown>> {
+    const cwd = (inputs.cwd as string) ?? context.cwd;
+    const result = await runFix({
+      cwd,
+      agent: (inputs.agent as string) ?? context.agent,
+      strict: Boolean(inputs.strict),
+      dryRun: Boolean(inputs.dryRun),
+      log: context.log
+    });
+    return {
+      applied: result.applied,
+      finalPass: result.finalPass,
+      reportPath: result.reportPath,
+      targetCount: result.proposal.targets.length
+    };
+  }
+};

package/src/skills/generate-artifact-skill.ts

@@ -0,0 +1,32 @@
+import { generateArtifact } from "../core/artifacts";
+import type { Skill } from "./types";
+
+export const generateArtifactSkill: Skill = {
+  manifest: {
+    name: "generate-artifact",
+    description: "Generate a single artifact (PRD, workflow, wireframe, stories, techspec)",
+    category: "artifact",
+    inputs: [
+      { name: "cwd", type: "path", required: true, description: "Project working directory" },
+      { name: "artifactType", type: "string", required: true, description: "Artifact type to generate" },
+      { name: "from", type: "path", required: false, description: "Override path to normalized-brief.json" },
+      { name: "out", type: "path", required: false, description: "Override output path" }
+    ],
+    outputs: [
+      { name: "filePath", type: "path", description: "Path to generated artifact" }
+    ]
+  },
+
+  async execute(context, inputs): Promise<Record<string, unknown>> {
+    const cwd = (inputs.cwd as string) ?? context.cwd;
+    const filePath = await generateArtifact({
+      artifactType: inputs.artifactType as string,
+      cwd,
+      normalizedBriefOverride: inputs.from as string | undefined,
+      outPath: inputs.out as string | undefined,
+      agent: context.agent
+    });
+    context.log(`${(inputs.artifactType as string).toUpperCase()} generated: ${filePath}`);
+    return { filePath };
+  }
+};

package/src/skills/generate-pipeline-skill.ts

@@ -0,0 +1,49 @@
+import { listArtifactTypes } from "../core/artifact-registry";
+import { generateArtifact } from "../core/artifacts";
+import { runNormalize } from "../core/normalize";
+import { runValidate } from "../core/validate";
+import type { Skill } from "./types";
+
+export const generatePipelineSkill: Skill = {
+  manifest: {
+    name: "generate-pipeline",
+    description: "Run end-to-end pipeline: normalize → generate all artifacts → validate",
+    category: "core",
+    inputs: [
+      { name: "cwd", type: "path", required: true, description: "Project working directory" },
+      { name: "strict", type: "boolean", required: false, description: "Treat warnings as errors" }
+    ],
+    outputs: [
+      { name: "pass", type: "string", description: "Whether validation passed" },
+      { name: "reportPath", type: "path", description: "Path to validation report" },
+      { name: "artifactCount", type: "string", description: "Number of artifacts generated" }
+    ]
+  },
+
+  async execute(context, inputs): Promise<Record<string, unknown>> {
+    const cwd = (inputs.cwd as string) ?? context.cwd;
+
+    const normalizedPath = await runNormalize({ cwd });
+    context.log(`Normalized brief: ${normalizedPath}`);
+
+    const artifactTypes = await listArtifactTypes(cwd);
+    for (const type of artifactTypes) {
+      const file = await generateArtifact({
+        artifactType: type,
+        cwd,
+        normalizedBriefOverride: normalizedPath,
+        agent: context.agent
+      });
+      context.log(`${type.toUpperCase()} generated: ${file}`);
+    }
+
+    const result = await runValidate(cwd, { strict: Boolean(inputs.strict) });
+    context.log(`Validation ${result.pass ? "passed" : "failed"}: ${result.reportPath}`);
+
+    return {
+      pass: result.pass,
+      reportPath: result.reportPath,
+      artifactCount: artifactTypes.length
+    };
+  }
+};

package/src/skills/normalize-skill.ts

@@ -0,0 +1,29 @@
+import { runNormalize } from "../core/normalize";
+import type { Skill } from "./types";
+
+export const normalizeSkill: Skill = {
+  manifest: {
+    name: "normalize",
+    description: "Normalize a product brief into structured JSON with contracts and confidence scores",
+    category: "core",
+    inputs: [
+      { name: "cwd", type: "path", required: true, description: "Project working directory" },
+      { name: "brief", type: "path", required: false, description: "Override path to brief.md" },
+      { name: "out", type: "path", required: false, description: "Override output path" }
+    ],
+    outputs: [
+      { name: "normalizedBriefPath", type: "path", description: "Path to normalized-brief.json" }
+    ]
+  },
+
+  async execute(context, inputs): Promise<Record<string, unknown>> {
+    const cwd = (inputs.cwd as string) ?? context.cwd;
+    const outPath = await runNormalize({
+      cwd,
+      brief: inputs.brief as string | undefined,
+      out: inputs.out as string | undefined
+    });
+    context.log(`Normalized brief written to: ${outPath}`);
+    return { normalizedBriefPath: outPath };
+  }
+};

package/src/skills/types.ts

@@ -0,0 +1,36 @@
+export type SkillInput = {
+  name: string;
+  type: "path" | "string" | "boolean" | "json";
+  required: boolean;
+  description: string;
+};
+
+export type SkillOutput = {
+  name: string;
+  type: "path" | "string" | "json";
+  description: string;
+};
+
+export type SkillManifest = {
+  name: string;
+  description: string;
+  category: "core" | "artifact" | "validation" | "custom";
+  inputs: SkillInput[];
+  outputs: SkillOutput[];
+};
+
+export type SkillContext = {
+  cwd: string;
+  log: (message: string) => void;
+  agent?: string;
+};
+
+export type SkillFunction = (
+  context: SkillContext,
+  inputs: Record<string, unknown>
+) => Promise<Record<string, unknown>>;
+
+export type Skill = {
+  manifest: SkillManifest;
+  execute: SkillFunction;
+};

package/src/skills/validate-skill.ts

@@ -0,0 +1,29 @@
+import { runValidate } from "../core/validate";
+import type { Skill } from "./types";
+
+export const validateSkill: Skill = {
+  manifest: {
+    name: "validate",
+    description: "Run cross-artifact validation and generate a report",
+    category: "validation",
+    inputs: [
+      { name: "cwd", type: "path", required: true, description: "Project working directory" },
+      { name: "strict", type: "boolean", required: false, description: "Treat warnings as errors" },
+      { name: "report", type: "path", required: false, description: "Override report output path" }
+    ],
+    outputs: [
+      { name: "pass", type: "string", description: "Whether validation passed" },
+      { name: "reportPath", type: "path", description: "Path to validation report" }
+    ]
+  },
+
+  async execute(context, inputs): Promise<Record<string, unknown>> {
+    const cwd = (inputs.cwd as string) ?? context.cwd;
+    const result = await runValidate(cwd, {
+      strict: Boolean(inputs.strict),
+      report: inputs.report as string | undefined
+    });
+    context.log(`Validation ${result.pass ? "passed" : "failed"}: ${result.reportPath}`);
+    return { pass: result.pass, reportPath: result.reportPath, issueCount: result.issues.length };
+  }
+};

package/templates/commands/prodo-fix.md

@@ -0,0 +1,46 @@
+---
+description: Fix failing artifacts using latest validation report and brief-aligned regeneration.
+agent-role: "Recovery Engineer"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+## Execution Policy
+
+- Execute-first, diagnose-second.
+- Do not run shell commands or CLI commands from inside the agent.
+- Never invoke `prodo-fix`, `prodo fix`, or any `prodo ...` command in shell.
+- Input files are read-only; never modify `brief.md`.
+- Write outputs only under `product-docs/` and `.prodo/`.
+- Do not print full artifact bodies in chat.
+
+## Execution
+
+1. Minimum prerequisites only:
+- `.prodo/` exists
+- `brief.md` exists
+- `.prodo/briefs/normalized-brief.json` exists (refresh if stale)
+- Validation report exists in `product-docs/reports/`
+
+2. Execute fix process immediately:
+- Read latest validation report.
+- Identify failing artifact types and regenerate only impacted chain.
+- Use normalized brief + active templates for regeneration.
+
+3. Verify result:
+- Re-run validation.
+- Confirm report status is PASS.
+- Confirm `brief.md` remained unchanged.
+
+4. Diagnose only on failure:
+- Inspect internal hooks/scripts only after fix attempt fails.
+- Return concise root cause + next repair action.
+
+## Handoff
+
+If pass: suggest next command `/prodo-validate`.
+If fail: suggest highest-priority artifact command to regenerate manually.

package/templates/commands/prodo-normalize.md

@@ -1,31 +1,126 @@
 ---
-description: Normalize product brief.
+description: >
+  Transform product brief into normalized, standardized JSON schema for downstream artifact generation.
+  Validates structure, enriches metadata, and ensures semantic consistency across all product definitions.
+agent-role: "Data Processor & Validator"
+agent-profile: |
+  **Character**: Meticulous Data Architect
+  - **Personality**: Precise, methodical, quality-focused
+  - **Specialization**: Schema validation, data normalization, integrity auditing
+  - **Decision Style**: Rule-based, deterministic (no guessing)
+  - **Tolerance**: Zero tolerance for data corruption or inconsistency
+  
+agent-skills: |
+  ✓ **Core Skills**:
+    - JSON schema validation & transformation
+    - Data normalization & standardization
+    - Metadata enrichment (timestamps, hashing, versioning)
+    - Deterministic output generation
+    - Integrity verification & audit trail
+  
+  ✓ **Performance Metrics**:
+    - Speed: Fast (one-pass processing)
+    - Accuracy: 100% deterministic
+    - Safety: Immutable input protection
+    - Reliability: No side effects
+  
+  ✓ **Problem-Solving Approach**:
+    - Fail-fast on validation errors
+    - Detect corruption early
+    - Auto-correct when possible
+    - Provide clear diagnostics on failure
+
+agent-decision-strategy: |
+  **Decision Tree**:
+  1. Prerequisites valid? → Continue | Fail-fast
+  2. Input corrupted? → Report error | Auto-correct if safe
+  3. Output format invalid? → Rewrite as pure JSON | Report conversion
+  4. Integrity compromised? → Report issue with remediation | Block output
+  
+  **When to Escalate**: 
+  - Input file missing or unreadable → User must provide
+  - Normalization logic ambiguous → Recommend upstream clarification
+  - Multiple corruption patterns detected → Suggest expert review
+
+agent-efficiency-tips: |
+  ⚡ **For Maximum Efficiency**:
+  - Run FIRST in pipeline (all others depend on this)
+  - Cache results: normalized-brief.json rarely changes
+  - Single pass: read once, validate, write
+  - No re-processing: output is deterministic
+  - Early validation: catch brief issues immediately
 ---
 
-## User Input
+## Context
+
+**Purpose**: Convert unstructured or semi-structured product brief into a machine-readable normalized format.
+
+**Upstream Dependencies**: `brief.md` must exist in project root.
+
+**Downstream Impact**: All artifact generation commands (PRD, stories, techspec, workflow, wireframe) depend on normalized-brief.json for consistency.
+
+**User Input**
 
 ```text
 $ARGUMENTS
 ```
 
-Execution policy:
-- Execute-first, diagnose-second.
-- Do not run shell/CLI commands from inside the agent.
-- Never run `prodo-normalize`, `prodo normalize`, or `prodo ...` in shell.
-- Input files are read-only; never modify or rewrite `brief.md`.
-- Never print full normalized JSON in chat.
-- Write `.prodo/briefs/normalized-brief.json`, then reply with short status + file path.
-
-## Execution
-
-1. Verify minimal prerequisites (`.prodo/`, `brief.md`).
-2. Read only `brief.md` and normalize it into `.prodo/briefs/normalized-brief.json`.
-3. Confirm `.prodo/briefs/normalized-brief.json` exists.
-4. Verify normalized file is strict JSON only:
-   - first non-space char is `{`
-   - no markdown fences like ```json or ```
-   - JSON parses successfully as an object
-5. If format is not strict JSON, rewrite the same file as pure JSON object only.
-6. Confirm `brief.md` content did not change.
-7. Do not create any manual files under `.prodo/` except expected runtime outputs.
-8. Diagnose internals only if command fails.
+## Execution Policy
+
+**Safety & Integrity**:
+- Execute-first, diagnose-second (fail fast on validation errors).
+- Do not execute shell/CLI commands from inside the agent.
+- Never invoke `prodo-normalize`, `prodo normalize`, or `prodo ...` commands recursively in shell.
+- **Input files are read-only**: Never modify, rewrite, or transform `brief.md`. Treat it as immutable source of truth.
+- Never print full normalized JSON to chat; return only status + file path.
+
+**Output Quality**:
+- Write `.prodo/briefs/normalized-brief.json` with validated strict JSON format.
+- Normalized output must be deterministic (same input always produces identical output).
+- Include metadata: normalized timestamp, schema version, input hash for audit trail.
+
+## Execution Steps
+
+1. **Verify Minimal Prerequisites**
+   - Confirm `.prodo/` directory exists (initialized by `prodo init`).
+   - Confirm `brief.md` exists and is readable.
+   - Check no corrupt `.prodo/briefs/` state exists.
+
+2. **Parse and Normalize `brief.md`**
+   - Read `brief.md` without modification.
+   - Extract and validate core product attributes (name, description, goals, target audience, scope, constraints).
+   - Normalize field types: trim whitespace, standardize arrays, convert dates to ISO-8601.
+   - Enrich with derived metadata (section count, complexity score, validation flags).
+
+3. **Validate Normalized Format**
+   - Confirm `.prodo/briefs/normalized-brief.json` was created.
+   - Verify strict JSON compliance:
+     - First non-space character must be `{`.
+     - No markdown fences (no \`\`\`json or \`\`\`).
+     - File must parse successfully as a valid JSON object.
+     - No trailing commas, unquoted keys, or comments.
+   - If format is invalid, rewrite file as pure JSON object only (auto-correct).
+
+4. **Audit & Verify Integrity**
+   - Confirm original `brief.md` was not modified (compare timestamps or file hash).
+   - Verify normalized output contains no executable code or shell injections.
+   - Log schema version and normalized metadata.
+
+5. **Safety Constraints**
+   - Do not create manual fallback files under `.prodo/` outside expected outputs.
+   - Do not write to `.prodo/templates/`, `.prodo/config/`, or other reserved directories.
+   - Do not modify or create `.gitignore` or hidden system files.
+
+6. **Diagnosis & Error Handling**
+   - If `brief.md` is missing: report clear error with recovery instructions.
+   - If `brief.md` syntax is invalid: report line numbers and invalid fields.
+   - If normalization fails: include schema mismatch details and sample valid structure.
+   - If `.prodo/briefs/` cannot be written: report file system permissions issue.
+
+## Success Criteria
+
+- ✅ `.prodo/briefs/normalized-brief.json` exists and is valid JSON.
+- ✅ Original `brief.md` remains unchanged.
+- ✅ Normalized file includes schema version and timestamp.
+- ✅ All required product attributes are present and validated.
+- ✅ Ready for downstream artifact generation.