@ncoderz/awa 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ncoderz/awa",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "awa is an Agent Workflow for AIs. It is also a CLI tool to powerfully manage agent workflow files using templates.",
   "license": "MIT",
   "repository": {
@@ -16,14 +16,15 @@
     "init": "tsx scripts/init.ts",
     "dev": "tsx src/cli/index.ts",
     "start": "node dist/index.js",
-    "build": "npm run init && npm run lint && npm run typecheck:all && tsup",
+    "build": "npm run init && npm run check && npm run lint && npm run typecheck:all && tsup",
     "gen:example": "tsx src/cli/index.ts generate ./outputs/example --template ./templates/example",
     "gen:awa": "tsx src/cli/index.ts generate ./outputs/awa --template ./templates/awa",
-    "gen:awa:this": "tsx src/cli/index.ts generate . --template ./templates/awa copilot",
+    "gen:awa:this": "tsx src/cli/index.ts generate . --template ./templates/awa --features copilot",
     "diff:awa:this": "tsx src/cli/index.ts diff . --template ./templates/awa --features copilot",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "check": "npm run dev -- check",
     "lint": "biome check --error-on-warnings .",
     "lint:fix": "biome check --error-on-warnings --fix .",
     "format": "biome format --write .",
@@ -63,11 +64,16 @@
     "diff": "^8.0.3",
     "eta": "^4.5.1",
     "isbinaryfile": "^6.0.0",
-    "smol-toml": "^1.6.0"
+    "remark-gfm": "^4.0.1",
+    "remark-parse": "^11.0.0",
+    "smol-toml": "^1.6.0",
+    "unified": "^11.0.5",
+    "yaml": "^2.8.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2",
     "@types/degit": "^2.8.6",
+    "@types/mdast": "^4.0.4",
     "@types/node": "^25.3.0",
     "@vitest/coverage-v8": "^4.0.18",
     "fast-check": "^4.5.3",

package/templates/awa/.agent/skills/awa-align/SKILL.md

@@ -0,0 +1,3 @@
+<% if (it.features.includes('agy')) { %>
+<%~ include('_partials/_skill.awa-align.md', it) %>
+<% } %>

package/templates/awa/.agent/skills/awa-check/SKILL.md

@@ -0,0 +1,4 @@
+<% if (it.features.includes('agy')) { %>
+<%~ include('_partials/_skill.awa-check.md', it) %>
+<% } %>
+

package/templates/awa/.agent/workflows/awa-align.md

@@ -0,0 +1,3 @@
+<% if (it.features.includes('agy')) { %>
+<%~ include('_partials/_cmd.awa-align.md', it) %>
+<% } %>

package/templates/awa/.agent/workflows/awa-check.md

@@ -0,0 +1,4 @@
+<% if (it.features.includes('agy')) { %>
+<%~ include('_partials/_cmd.awa-check.md', it) %>
+<% } %>
+

package/templates/awa/.agents/skills/awa-align/SKILL.md

@@ -0,0 +1,3 @@
+<% if (it.features.includes('codex')) { %>
+<%~ include('_partials/_skill.awa-align.md', it) %>
+<% } %>

package/templates/awa/.agents/skills/awa-check/SKILL.md

@@ -0,0 +1,4 @@
+<% if (it.features.includes('codex')) { %>
+<%~ include('_partials/_skill.awa-check.md', it) %>
+<% } %>
+

package/templates/awa/.awa/.agent/schemas/ALIGN_REPORT.schema.yaml

@@ -0,0 +1,83 @@
+# Structural rules for ALIGN-{x}-WITH-{y}-{nnn}.md files
+target-files: ".awa/align/ALIGN-*.md"
+description: >
+  Alignment report comparing a source artifact (x) with a target artifact (y).
+  Each finding has a severity (CRITICAL/MAJOR/MINOR/INFO), confidence
+  (CERTAIN/LIKELY/UNCERTAIN), and type (MISSING/DIFFERENCE/CONFLICT/INCOMPLETE/
+  UNTESTED/ORPHAN/SUPERSET). Findings are checkbox items with SOURCE, TARGET,
+  ISSUE, and RESOLUTION fields. Summary section has severity counts and STATUS.
+line-limit: 500
+
+sections:
+  # Top-level heading
+  - heading: "ALIGNMENT REPORT"
+    level: 1
+    required: true
+    description: >
+      Document title followed by the comparison line:
+      {source-artifact} ↔ {target-artifact}
+      Then a list of findings as checkbox items.
+    contains:
+      # Findings are checkbox list items
+      - list:
+          pattern: "\\[[ x]\\].*\\b(CRITICAL|MAJOR|MINOR|INFO)\\b"
+          min: 1
+          label: "finding items"
+        description: >
+          Checkbox items for each finding. Format:
+          - [ ] N. {SEVERITY} [{CONFIDENCE}] {TYPE}
+            SOURCE: {location}
+            > {source text}
+            TARGET: {location}
+            > {target text}
+            ISSUE: {description}
+            RESOLUTION: {action}
+        required: false
+
+  # Summary section
+  - heading: "Summary"
+    level: 2
+    required: true
+    description: >
+      Severity counts and pass/fail status. Format:
+      CRITICAL: {n}
+      MAJOR: {n}
+      MINOR: {n}
+      INFO: {n}
+      STATUS: PASSED or FAILED
+    contains:
+      - pattern: "^(CRITICAL|MAJOR|MINOR|INFO):"
+        label: "severity count"
+        description: "One line per severity level with count."
+      - pattern: "^STATUS:"
+        label: "STATUS line"
+        description: "STATUS: PASSED or STATUS: FAILED (with optional emoji)."
+
+example: |
+  # ALIGNMENT REPORT
+
+  DESIGN-WKS-workspace.md ↔ src/workspace/**
+
+  - [ ] 1. CRITICAL [CERTAIN] MISSING
+    SOURCE: WKS-WorkspaceConfig (IMPLEMENTS: WKS-1_AC-1)
+    > pub fn load(root: &Path) -> Result<Self, WorkspaceError>
+    TARGET: (not found)
+    ISSUE: Design component declares IMPLEMENTS: WKS-1_AC-1, but no code file contains @awa-component: WKS-WorkspaceConfig.
+    RESOLUTION: Add @awa-component: WKS-WorkspaceConfig to src/workspace/config.rs
+
+  - [ ] 2. MAJOR [CERTAIN] DIFFERENCE
+    SOURCE: WKS-WorkspaceValidator (IMPLEMENTS: WKS-2_AC-3)
+    > fn validate(&self) -> Result<(), ValidationError>
+    TARGET: src/workspace/validator.rs:45
+    > fn validate(&self) -> bool
+    ISSUE: Return type mismatch. Design specifies Result but implementation returns bool.
+    RESOLUTION: Update validator.rs to return Result<(), ValidationError>
+
+  ## Summary
+
+  CRITICAL: 1
+  MAJOR: 1
+  MINOR: 0
+  INFO: 0
+
+  STATUS: FAILED

package/templates/awa/.awa/.agent/schemas/API.schema.yaml

@@ -0,0 +1,7 @@
+# Structural rules for API-{CODE}-{api-name}.tsp files
+target-files: ".awa/specs/API-*.tsp"
+description: >
+  TypeSpec API specification. Defines major APIs using TypeSpec format
+  conventions. Write in TypeSpec unless explicitly requested otherwise.
+  One file per API surface area, named with the feature CODE prefix.
+line-limit: 500

package/templates/awa/.awa/.agent/schemas/ARCHITECTURE.schema.yaml

@@ -0,0 +1,260 @@
+# Structural rules for ARCHITECTURE.md
+target-files: ".awa/specs/ARCHITECTURE.md"
+description: >
+  High-level architecture overview for the project. Succinct language.
+  Do not overspecify or include implementation details. Covers project purpose,
+  system layers, technology stack, top-level architecture diagram, directory structure,
+  component details with RESPONSIBILITIES, interactions, rules, and
+  developer commands. Delegate to feature and design files where appropriate.
+  One file per project.
+line-limit: 800
+
+sections:
+  # Top-level heading
+  - heading: "Architecture"
+    level: 1
+    required: true
+    description: "Document title. No metadata in this section."
+
+  # Project Purpose section
+  - heading: "Project Purpose"
+    level: 2
+    required: true
+    description: >
+      Single paragraph: core problem and primary functionality.
+      What the project does and why it exists.
+
+  # System Overview section
+  - heading: "System Overview"
+    level: 2
+    required: true
+    description: >
+      Bullet list of software layers or subsystems (e.g., CLI Layer,
+      Core Engine, Template System, I/O Layer).
+
+  # Technology Stack section
+  - heading: "Technology Stack"
+    level: 2
+    required: true
+    description: >
+      Bullet list of technologies with major version only.
+      Format: - `{Technology N}` — {purpose}
+
+  # High-Level Architecture section with mermaid diagram
+  - heading: "High-Level Architecture"
+    level: 2
+    required: true
+    description: >
+      Mermaid diagram showing components, data flow, and dependencies.
+      Must include a mermaid code block.
+    contains:
+      - code-block: true
+        label: "architecture diagram (mermaid)"
+        description: "Mermaid diagram (flowchart, sequence, etc.) showing the architecture."
+
+  # Directory Structure section
+  - heading: "Directory Structure"
+    level: 2
+    required: true
+    description: >
+      Code block with directory tree showing source layout.
+      Format: path/  # description
+    contains:
+      - code-block: true
+        label: "directory tree"
+        description: "Plain text directory tree with inline comments."
+
+  # Component Details section
+  - heading: "Component Details"
+    level: 2
+    required: true
+    description: >
+      One H3 per major component. Each component has a single-sentence
+      description, RESPONSIBILITIES list, and optional CONSTRAINTS list.
+    children:
+      - heading: ".*"
+        level: 3
+        repeatable: true
+        required: true
+        description: >
+          Component heading. Contains a single-sentence description,
+          RESPONSIBILITIES bullet list, and optional CONSTRAINTS bullet list.
+        contains:
+          - pattern: "RESPONSIBILITIES"
+            label: "RESPONSIBILITIES section"
+            description: "Keyword followed by a bullet list of component responsibilities."
+
+  # Component Interactions section
+  - heading: "Component Interactions"
+    level: 2
+    required: true
+    description: >
+      Describes how components communicate. May include mermaid sequence
+      diagrams as H3 subsections.
+
+  # Architectural Rules section
+  - heading: "Architectural Rules"
+    level: 2
+    required: true
+    description: >
+      Bullet list of rules covering performance, scaling, maintainability,
+      security, and testing constraints.
+
+  # Release Status section (optional)
+  - heading: "Release Status"
+    level: 2
+    description: >
+      Current release phase (Alpha, Beta, RC, GA) with brief description.
+      Format: STATUS: {phase} - {description}
+
+  # Developer Commands section
+  - heading: "Developer Commands"
+    level: 2
+    required: true
+    description: >
+      Bullet list of essential developer commands.
+      Format: - `{command}` - {description}
+
+  # Change Log section (optional)
+  - heading: "Change Log"
+    level: 2
+    description: "Version history. Format: - {version} ({date}): {changes}"
+
+sections-prohibited:
+  - "**"
+
+example: |
+  # Architecture
+
+  ## Project Purpose
+
+  awa CLI generates AI coding agent configuration files from templates, enabling developers to quickly scaffold consistent agent setups across projects.
+
+  ## System Overview
+
+  - CLI Layer
+  - Core Engine
+  - Template System
+  - I/O Layer
+
+  ## Technology Stack
+
+  - `Node.js 20` — Runtime environment
+  - `TypeScript 5` — Type-safe development
+  - `Eta 3` — Template rendering
+  - `Citty` — CLI framework
+
+  ## High-Level Architecture
+
+  ```mermaid
+  flowchart LR
+      subgraph Input
+          Args[CLI Args]
+          Config[.awa.toml]
+          Templates[Templates]
+      end
+      subgraph Core
+          Parser[ArgumentParser]
+          Engine[TemplateEngine]
+          Generator[FileGenerator]
+      end
+      subgraph Output
+          Files[Generated Files]
+      end
+      Args --> Parser
+      Config --> Parser
+      Parser --> Engine
+      Templates --> Engine
+      Engine --> Generator
+      Generator --> Files
+  ```
+
+  ## Directory Structure
+
+  ```
+  src/           # Source code
+  src/cli/       # CLI entry and commands
+  src/core/      # Core engine logic
+  src/utils/     # Shared utilities
+  templates/     # Bundled templates
+  ```
+
+  ## Component Details
+
+  ### CLI Layer
+
+  Handles argument parsing and command dispatch.
+
+  RESPONSIBILITIES
+
+  - Parse CLI arguments and options
+  - Load and merge configuration
+  - Dispatch to appropriate command handlers
+
+  CONSTRAINTS
+
+  - Must fail fast on invalid arguments
+  - Must support --help and --version
+
+  ### Template Engine
+
+  Renders templates with feature flag context.
+
+  RESPONSIBILITIES
+
+  - Load templates from local or remote sources
+  - Render with Eta templating
+  - Detect empty output for conditional file creation
+
+  ### File Generator
+
+  Writes rendered output to the file system.
+
+  RESPONSIBILITIES
+
+  - Write files with conflict detection
+  - Support dry-run mode
+  - Generate diff output
+
+  ## Component Interactions
+
+  The CLI parses arguments, loads configuration, then passes resolved options to the template engine which renders files through the generator.
+
+  ### Generate Command Flow
+
+  ```mermaid
+  sequenceDiagram
+      participant User
+      participant CLI
+      participant Engine
+      participant Generator
+      User->>CLI: awa generate
+      CLI->>Engine: render(templates, features)
+      Engine->>Generator: write(files)
+      Generator-->>User: Success summary
+  ```
+
+  ## Architectural Rules
+
+  - All file I/O must go through the I/O layer
+  - Core engine must not depend on CLI layer
+  - Templates must be stateless and deterministic
+  - Errors must provide actionable messages with file paths
+  - All public APIs must have TypeScript types
+
+  ## Release Status
+
+  STATUS: Alpha — Core functionality implemented. API may change without notice.
+
+  ## Developer Commands
+
+  - `npm install` — Install dependencies
+  - `npm run dev` — Run in development mode
+  - `npm test` — Run test suite
+  - `npm run lint` — Run linter
+  - `npm run build` — Build for production
+
+  ## Change Log
+
+  - 1.0.0 (2025-01-10): Initial architecture
+  - 1.1.0 (2025-01-15): Added diff command