@devtrack-solution/codesdd 1.2.2

package/dist/core/sdd/default-skills.d.ts

@@ -0,0 +1,16 @@
+import type { SkillCatalogState } from './types.js';
+export interface BuiltInSkillSourceTree {
+    kind: 'source-tree';
+    sourceRoot: string;
+}
+export type BuiltInSkillTree = Record<string, string>;
+export type BuiltInSkillDefinition = string | BuiltInSkillTree | BuiltInSkillSourceTree;
+export declare const DEFAULT_CURATED_SKILL_CATALOG: SkillCatalogState;
+export declare const SOURCE_INTAKE_SDD_SKILL_MD = "---\nname: source-intake-sdd\ndescription: Reads the .sdd/sources folder, indexes raw sources, and classifies project intake material.\n---\n\n# Source Intake SDD\n\nUse this skill when the project has raw material in `.sdd/sources/`.\n\n## Objective\n\nTurn a heterogeneous document set into a traceable operational inventory.\n\n## Where To Look\n\n- `.sdd/sources/prds/`\n- `.sdd/sources/rfcs/`\n- `.sdd/sources/briefings/`\n- `.sdd/sources/stories/`\n- `.sdd/sources/wireframes/`\n- `.sdd/sources/html-mocks/`\n- `.sdd/sources/visual-references/`\n- `.sdd/sources/interviews/`\n- `.sdd/sources/attachments/`\n- `.sdd/sources/legacy/`\n\n## Required Flow\n\n1. List existing sources.\n2. Classify each source by type.\n3. Register/update `.sdd/state/source-index.yaml`.\n4. Fill for each item:\n   - `type`\n   - `path`\n   - `title`\n   - `status`\n   - `summary`\n   - `used_by`\n   - `consolidation_targets`\n5. Do not generate backlog directly in this step.\n\n## Golden Rule\n\n- Raw source is not canonical source.\n- The goal here is inventory and classification.\n- Backlog is created only after semantic normalization.\n";
+export declare const BUSINESS_EXTRACTOR_SDD_SKILL_MD = "---\nname: business-extractor-sdd\ndescription: Extracts stories, business rules, actors, integrations, and constraints from source material.\n---\n\n# Business Extractor SDD\n\nUse this skill when the repository already has PRDs, briefings, stories, or consolidated documents.\n\n## Expected Outputs\n\n- canonical context updates:\n  - `.sdd/state/architecture.yaml`\n  - `.sdd/state/service-catalog.yaml`\n  - `.sdd/state/tech-stack.yaml`\n  - `.sdd/state/integration-contracts.yaml`\n- suggestions for:\n  - EPICs\n  - FEATs\n  - INSIGHTs only when real ambiguity exists\n\n## How To Decide The Destination\n\n- If the excerpt describes system structure, consolidate it into context.\n- If the excerpt is a large approved decision, normalize it into an EPIC.\n- If the excerpt is already clear and executable, normalize it into a FEAT.\n- If the excerpt is ambiguous, contradictory, or incomplete, normalize it into an INSIGHT.\n\n## Do Not\n\n- Do not turn an entire PRD into a direct task list.\n- Do not invent technical details that are not present in the source.\n";
+export declare const FRONTEND_EXTRACTOR_SDD_SKILL_MD = "---\nname: frontend-extractor-sdd\ndescription: Extracts frontend surfaces, routes, components, gaps, and decisions from images, HTML, wireframes, and references.\n---\n\n# Frontend Extractor SDD\n\nUse this skill when visual inspiration or UI/UX definitions exist in `.sdd/sources/`.\n\n## Accepted Sources\n\n- wireframes\n- screenshots\n- reference images\n- mocked HTML\n- stories with interface impact\n\n## Expected Outputs\n\n- `.sdd/state/frontend-map.yaml`\n- `.sdd/state/frontend-gaps.yaml`\n- `.sdd/state/frontend-decisions.yaml`\n\n## Classification Criteria\n\n- What is clearly defined as a screen/route goes into frontend-map.\n- What is missing but necessary to cover the journey goes into frontend-gaps.\n- UX rationale, navigation, layout, patterns, and inspiration go into frontend-decisions.\n- If a surface is well-defined and executable, it can become a FEAT.\n";
+export declare const PLANNING_NORMALIZER_SDD_SKILL_MD = "---\nname: planning-normalizer-sdd\ndescription: Converts extracted source material into the SDD operational backlog, prioritizing context, EPICs, and FEATs.\n---\n\n# Planning Normalizer SDD\n\nUse this skill after inventorying sources and extracting business/frontend context.\n\n## Mission\n\nTurn consolidated knowledge into operational SDD artifacts.\n\n## Normalization Order\n\n1. canonical context\n2. EPICs\n3. FEATs\n4. INSIGHTs only for exceptions\n\n## Rules\n\n- Do not force debate when the source is already consolidated and unambiguous.\n- Use debate only for uncertainty, conflict, ambiguity, or open architecture options.\n- Connect FEATs with `blocked_by`, `lock_domains`, `produces`, and `consumes` when enough evidence exists.\n- Record in `.sdd/state/source-index.yaml` which sources generated each EPIC/FEAT.\n\n## Minimum Result\n\nAt the end, the agent must be able to answer:\n- what is system context;\n- what is already approved for planning;\n- what can enter execution now.\n";
+export declare function buildCuratedBundlesMarkdown(): string;
+export declare const REPO_CONTEXT_BOOTSTRAP_SKILL_MD: string;
+export declare const BUILT_IN_SDD_SKILLS: Record<string, BuiltInSkillDefinition>;
+//# sourceMappingURL=default-skills.d.ts.map

package/dist/core/sdd/default-skills.js

@@ -0,0 +1,427 @@
+import { CLI_NAME } from '../branding.js';
+const DEFAULT_TOOLS = ['codex', 'cursor', 'claude', 'gemini'];
+const DEFAULT_SOURCE_REPO = 'https://github.com/sickn33/antigravity-awesome-skills';
+const LOCAL_SDD_SKILL_PATHS = {
+    'api-clean-flask-langgraph': '.sdd/skills/curated/api-clean-flask-langgraph/SKILL.md',
+    'devtrack-api': '.sdd/skills/curated/devtrack-api/SKILL.md',
+    'source-intake-sdd': '.sdd/skills/curated/source-intake-sdd/SKILL.md',
+    'business-extractor-sdd': '.sdd/skills/curated/business-extractor-sdd/SKILL.md',
+    'frontend-extractor-sdd': '.sdd/skills/curated/frontend-extractor-sdd/SKILL.md',
+    'planning-normalizer-sdd': '.sdd/skills/curated/planning-normalizer-sdd/SKILL.md',
+    'mobile-design': '.sdd/skills/curated/sdd-curated-mobile-design/SKILL.md',
+};
+const SKILL_METADATA_OVERRIDES = {
+    'api-clean-flask-langgraph': {
+        title: 'API Clean Flask LangGraph',
+        description: 'Canonical Python/Flask agentic backend skill with Clean Architecture boundaries, tenant/security authority-source rules, OpenSDD decision support (runtime-safe), production-readiness guidance, and maintainable quality gates.',
+    },
+    'devtrack-api': {
+        title: 'DevTrack API',
+        description: 'Model-agnostic backend engineering and governance skill for DevTrack APIs using NestJS, TypeORM, DDD/Clean Architecture boundaries, evidence-based validation, and safe operational delivery.',
+    },
+};
+const CURATED_BUNDLES = [
+    {
+        id: 'source-intake',
+        title: 'Source Intake',
+        domains: ['intake', 'planning', 'frontend'],
+        phases: ['discover', 'plan'],
+        skillIds: [
+            'source-intake-sdd',
+            'business-extractor-sdd',
+            'frontend-extractor-sdd',
+            'planning-normalizer-sdd',
+        ],
+    },
+    {
+        id: 'essentials-core',
+        title: 'Essentials Core',
+        domains: ['general', 'process'],
+        phases: ['discover', 'plan', 'execute', 'verify', 'finalize'],
+        skillIds: [
+            'concise-planning',
+            'brainstorming',
+            'lint-and-validate',
+            'systematic-debugging',
+            'test-driven-development',
+            'doc-coauthoring',
+            'create-pr',
+            'git-pushing',
+            'kaizen',
+            'code-review-checklist',
+        ],
+    },
+    {
+        id: 'architecture-backend',
+        title: 'Architecture Backend',
+        domains: ['architecture', 'backend'],
+        phases: ['discover', 'plan', 'execute', 'verify'],
+        skillIds: [
+            'architecture',
+            'senior-architect',
+            'architecture-patterns',
+            'microservices-patterns',
+            'domain-driven-design',
+            'ddd-context-mapping',
+            'ddd-tactical-patterns',
+            'api-design-principles',
+            'database-design',
+            'devtrack-api',
+            'typescript-expert',
+        ],
+    },
+    {
+        id: 'python-agentic-backend',
+        title: 'Python Agentic Backend',
+        domains: ['backend', 'api', 'python', 'flask', 'websocket', 'ai', 'agent', 'saas'],
+        phases: ['plan', 'execute', 'verify', 'finalize'],
+        skillIds: ['api-clean-flask-langgraph'],
+    },
+    {
+        id: 'frontend-product',
+        title: 'Frontend Product',
+        domains: ['frontend', 'product'],
+        phases: ['plan', 'execute', 'verify'],
+        skillIds: [
+            'frontend-design',
+            'react-best-practices',
+            'react-patterns',
+            'nextjs-best-practices',
+            'nextjs-app-router-patterns',
+            'tailwind-patterns',
+            'ui-ux-pro-max',
+            'mobile-design',
+            'form-cro',
+            'frontend-developer',
+        ],
+    },
+    {
+        id: 'security-quality',
+        title: 'Security Quality',
+        domains: ['security', 'quality'],
+        phases: ['plan', 'execute', 'verify'],
+        skillIds: [
+            'security-auditor',
+            'api-security-best-practices',
+            'backend-security-coder',
+            'frontend-security-coder',
+            'cc-skill-security-review',
+            'top-web-vulnerabilities',
+            'vulnerability-scanner',
+            'ethical-hacking-methodology',
+            'cloud-penetration-testing',
+            'pci-compliance',
+        ],
+    },
+    {
+        id: 'ai-agentic',
+        title: 'AI Agentic',
+        domains: ['ai', 'agent'],
+        phases: ['discover', 'plan', 'execute', 'verify', 'finalize'],
+        skillIds: [
+            'prompt-engineering',
+            'context-window-management',
+            'ai-agents-architect',
+            'agent-evaluation',
+            'mcp-builder',
+            'rag-engineer',
+            'rag-implementation',
+            'prompt-caching',
+            'langgraph',
+            'langfuse',
+        ],
+    },
+    {
+        id: 'devops-integration',
+        title: 'DevOps Integration',
+        domains: ['devops', 'integration'],
+        phases: ['plan', 'execute', 'verify', 'finalize'],
+        skillIds: [
+            'docker-expert',
+            'aws-serverless',
+            'kubernetes-architect',
+            'terraform-specialist',
+            'environment-setup-guide',
+            'deployment-procedures',
+            'observability-engineer',
+            'distributed-tracing',
+            'performance-engineer',
+            'incident-responder',
+        ],
+    },
+];
+function titleFromSkillId(skillId) {
+    return skillId
+        .split('-')
+        .map((part) => (part.length > 0 ? part[0].toUpperCase() + part.slice(1) : part))
+        .join(' ');
+}
+function priorityForIndex(index) {
+    const priority = 10 - index;
+    return priority < 6 ? 6 : priority;
+}
+function buildSkillEntry(bundle, skillId, index) {
+    const localSourcePath = LOCAL_SDD_SKILL_PATHS[skillId];
+    const isLocalSkill = Boolean(localSourcePath);
+    const metadata = SKILL_METADATA_OVERRIDES[skillId] || {};
+    return {
+        id: skillId,
+        source_repo: isLocalSkill ? 'local://opensdd/sdd' : DEFAULT_SOURCE_REPO,
+        source_path: isLocalSkill ? localSourcePath : `skills/${skillId}/SKILL.md`,
+        title: metadata.title || titleFromSkillId(skillId),
+        description: metadata.description || (isLocalSkill
+            ? `Native SDD skill for ${bundle.title.toLowerCase()}.`
+            : `Curated skill for ${bundle.title.toLowerCase()} in the SDD flow.`),
+        phases: bundle.phases,
+        domains: bundle.domains,
+        tools: DEFAULT_TOOLS,
+        bundle_ids: [bundle.id],
+        priority: priorityForIndex(index),
+    };
+}
+export const DEFAULT_CURATED_SKILL_CATALOG = {
+    version: 1,
+    skills: CURATED_BUNDLES.flatMap((bundle) => bundle.skillIds.map((skillId, index) => buildSkillEntry(bundle, skillId, index))),
+    bundles: CURATED_BUNDLES.map((bundle) => ({
+        id: bundle.id,
+        title: bundle.title,
+        skill_ids: [...bundle.skillIds],
+    })),
+};
+export const SOURCE_INTAKE_SDD_SKILL_MD = `---
+name: source-intake-sdd
+description: Reads the .sdd/sources folder, indexes raw sources, and classifies project intake material.
+---
+
+# Source Intake SDD
+
+Use this skill when the project has raw material in \`.sdd/sources/\`.
+
+## Objective
+
+Turn a heterogeneous document set into a traceable operational inventory.
+
+## Where To Look
+
+- \`.sdd/sources/prds/\`
+- \`.sdd/sources/rfcs/\`
+- \`.sdd/sources/briefings/\`
+- \`.sdd/sources/stories/\`
+- \`.sdd/sources/wireframes/\`
+- \`.sdd/sources/html-mocks/\`
+- \`.sdd/sources/visual-references/\`
+- \`.sdd/sources/interviews/\`
+- \`.sdd/sources/attachments/\`
+- \`.sdd/sources/legacy/\`
+
+## Required Flow
+
+1. List existing sources.
+2. Classify each source by type.
+3. Register/update \`.sdd/state/source-index.yaml\`.
+4. Fill for each item:
+   - \`type\`
+   - \`path\`
+   - \`title\`
+   - \`status\`
+   - \`summary\`
+   - \`used_by\`
+   - \`consolidation_targets\`
+5. Do not generate backlog directly in this step.
+
+## Golden Rule
+
+- Raw source is not canonical source.
+- The goal here is inventory and classification.
+- Backlog is created only after semantic normalization.
+`;
+export const BUSINESS_EXTRACTOR_SDD_SKILL_MD = `---
+name: business-extractor-sdd
+description: Extracts stories, business rules, actors, integrations, and constraints from source material.
+---
+
+# Business Extractor SDD
+
+Use this skill when the repository already has PRDs, briefings, stories, or consolidated documents.
+
+## Expected Outputs
+
+- canonical context updates:
+  - \`.sdd/state/architecture.yaml\`
+  - \`.sdd/state/service-catalog.yaml\`
+  - \`.sdd/state/tech-stack.yaml\`
+  - \`.sdd/state/integration-contracts.yaml\`
+- suggestions for:
+  - EPICs
+  - FEATs
+  - INSIGHTs only when real ambiguity exists
+
+## How To Decide The Destination
+
+- If the excerpt describes system structure, consolidate it into context.
+- If the excerpt is a large approved decision, normalize it into an EPIC.
+- If the excerpt is already clear and executable, normalize it into a FEAT.
+- If the excerpt is ambiguous, contradictory, or incomplete, normalize it into an INSIGHT.
+
+## Do Not
+
+- Do not turn an entire PRD into a direct task list.
+- Do not invent technical details that are not present in the source.
+`;
+export const FRONTEND_EXTRACTOR_SDD_SKILL_MD = `---
+name: frontend-extractor-sdd
+description: Extracts frontend surfaces, routes, components, gaps, and decisions from images, HTML, wireframes, and references.
+---
+
+# Frontend Extractor SDD
+
+Use this skill when visual inspiration or UI/UX definitions exist in \`.sdd/sources/\`.
+
+## Accepted Sources
+
+- wireframes
+- screenshots
+- reference images
+- mocked HTML
+- stories with interface impact
+
+## Expected Outputs
+
+- \`.sdd/state/frontend-map.yaml\`
+- \`.sdd/state/frontend-gaps.yaml\`
+- \`.sdd/state/frontend-decisions.yaml\`
+
+## Classification Criteria
+
+- What is clearly defined as a screen/route goes into frontend-map.
+- What is missing but necessary to cover the journey goes into frontend-gaps.
+- UX rationale, navigation, layout, patterns, and inspiration go into frontend-decisions.
+- If a surface is well-defined and executable, it can become a FEAT.
+`;
+export const PLANNING_NORMALIZER_SDD_SKILL_MD = `---
+name: planning-normalizer-sdd
+description: Converts extracted source material into the SDD operational backlog, prioritizing context, EPICs, and FEATs.
+---
+
+# Planning Normalizer SDD
+
+Use this skill after inventorying sources and extracting business/frontend context.
+
+## Mission
+
+Turn consolidated knowledge into operational SDD artifacts.
+
+## Normalization Order
+
+1. canonical context
+2. EPICs
+3. FEATs
+4. INSIGHTs only for exceptions
+
+## Rules
+
+- Do not force debate when the source is already consolidated and unambiguous.
+- Use debate only for uncertainty, conflict, ambiguity, or open architecture options.
+- Connect FEATs with \`blocked_by\`, \`lock_domains\`, \`produces\`, and \`consumes\` when enough evidence exists.
+- Record in \`.sdd/state/source-index.yaml\` which sources generated each EPIC/FEAT.
+
+## Minimum Result
+
+At the end, the agent must be able to answer:
+- what is system context;
+- what is already approved for planning;
+- what can enter execution now.
+`;
+export function buildCuratedBundlesMarkdown() {
+    const lines = [
+        '# Skill Curation (en-US)',
+        '',
+        `This file describes the initial curation of ${DEFAULT_CURATED_SKILL_CATALOG.skills.length} skills for SDD usage.`,
+        '',
+        '## Objective',
+        '- Reduce the 900+ skill universe to a practical set.',
+        '- Accelerate planning, execution, and validation.',
+        '- Make delegation between agents easier in English.',
+        '',
+    ];
+    CURATED_BUNDLES.forEach((bundle, index) => {
+        lines.push(`## Bundle ${index + 1}: ${bundle.title} (${bundle.skillIds.length})`);
+        bundle.skillIds.forEach((skillId) => lines.push(`- ${skillId}`));
+        lines.push('');
+    });
+    lines.push('## Highlighted Local Skill');
+    lines.push('- `api-clean-flask-langgraph` belongs to bundle `python-agentic-backend`.');
+    lines.push('- It is the canonical local reference for Python/Flask Clean Architecture, OpenSDD decision support (without runtime dependency), production-readiness guidance, and quality gates.');
+    lines.push('- Canonical file: `.sdd/skills/curated/api-clean-flask-langgraph/SKILL.md`.');
+    lines.push('- `devtrack-api` belongs to bundle `architecture-backend`.');
+    lines.push('- Canonical directory: `.sdd/skills/curated/devtrack-api/` (includes `agents/` and `references/`).');
+    lines.push('');
+    lines.push('## Canonical Source');
+    lines.push('- `.sdd/state/skill-catalog.yaml`');
+    lines.push('');
+    lines.push('## Operational Rule');
+    lines.push('- The skills in this document are a curation reference.');
+    lines.push('- Official skills and bundles state must be edited only in canonical YAML.');
+    lines.push('');
+    return lines.join('\n');
+}
+export const REPO_CONTEXT_BOOTSTRAP_SKILL_MD = `---
+name: repo-context-bootstrap
+description: Inspects an existing repository to fill initial SDD context with evidence and avoid fragile inference.
+---
+
+# Repo Context Bootstrap
+
+Use this skill when the project already exists and you need reliable initial SDD context.
+
+## Objective
+
+Map and document, based on repository evidence:
+- technology stack;
+- service catalog;
+- initial architecture;
+- integrations/contracts;
+- relevant directory map.
+
+## Required Flow
+
+1. Run \`${CLI_NAME} sdd init --frontend --lang en-US --layout en-US\` if the SDD structure does not exist yet.
+2. Execute \`${CLI_NAME} sdd init-context --mode merge\`.
+3. Read the generated files:
+   - \`.sdd/core/spec-tecnologica.md\`
+   - \`.sdd/core/servicos.md\`
+   - \`.sdd/core/arquitetura.md\`
+   - \`.sdd/core/repo-map.md\`
+4. Validate with \`${CLI_NAME} sdd check --render\`.
+5. Register any doubt or low confidence as a review item in \`.sdd/planning/tech-debt.md\`.
+
+## Quality Rules
+
+- Do not invent services that do not appear in directories or manifests.
+- Do not invent integrations without concrete signals in dependencies or configs.
+- Prioritize evidence in:
+  - \`package.json\`, \`pnpm-workspace.yaml\`, \`docker-compose.yml\`;
+  - directories \`apps/\`, \`services/\`, \`packages/\`, \`src/\`;
+  - framework configuration files.
+- When uncertain, record it as "needs human review".
+
+## Expected Result
+
+After execution, the project should have enough useful initial context for a new agent to continue without broad code inspection.
+`;
+export const BUILT_IN_SDD_SKILLS = {
+    'repo-context-bootstrap': REPO_CONTEXT_BOOTSTRAP_SKILL_MD,
+    'source-intake-sdd': SOURCE_INTAKE_SDD_SKILL_MD,
+    'business-extractor-sdd': BUSINESS_EXTRACTOR_SDD_SKILL_MD,
+    'frontend-extractor-sdd': FRONTEND_EXTRACTOR_SDD_SKILL_MD,
+    'planning-normalizer-sdd': PLANNING_NORMALIZER_SDD_SKILL_MD,
+    'api-clean-flask-langgraph': {
+        kind: 'source-tree',
+        sourceRoot: '.sdd/skills/curated/api-clean-flask-langgraph',
+    },
+    'devtrack-api': {
+        kind: 'source-tree',
+        sourceRoot: '.sdd/skills/curated/devtrack-api',
+    },
+};
+//# sourceMappingURL=default-skills.js.map

package/dist/core/sdd/diagnose.d.ts

@@ -0,0 +1,25 @@
+import { type StructuralDiagnosticReport } from './structural-health.js';
+export interface SddDiagnoseOptions {
+    strict?: boolean;
+}
+export interface SddDiagnoseCommandOptions extends SddDiagnoseOptions {
+    output?: string;
+}
+export interface SddDiagnoseResult {
+    report: StructuralDiagnosticReport;
+    exitCode: number;
+    health: 'HEALTHY' | 'WARNING' | 'ERROR' | 'BLOCKED';
+    outputPath?: string;
+}
+export declare class SddDiagnosticOptionsError extends Error {
+    constructor(message: string);
+}
+export declare function getDiagnosticExitCode(report: StructuralDiagnosticReport): number;
+export declare function getDiagnosticHealth(report: StructuralDiagnosticReport): SddDiagnoseResult['health'];
+export declare function diagnoseSddRoot(projectRoot: string, options?: SddDiagnoseOptions): Promise<StructuralDiagnosticReport>;
+export declare function writeDiagnosticReport(projectRoot: string, outputPath: string, report: StructuralDiagnosticReport): Promise<string>;
+export declare function formatDiagnosticText(report: StructuralDiagnosticReport): string;
+export declare class SddDiagnoseCommand {
+    execute(projectRoot: string, options?: SddDiagnoseCommandOptions): Promise<SddDiagnoseResult>;
+}
+//# sourceMappingURL=diagnose.d.ts.map