@ncoderz/awa 1.3.1 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ncoderz/awa",
-  "version": "1.3.1",
+  "version": "1.5.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": {
@@ -17,10 +17,10 @@
     "dev": "tsx src/cli/index.ts",
     "start": "node dist/index.js",
     "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 --features copilot",
-    "diff:awa:this": "tsx src/cli/index.ts diff . --template ./templates/awa --features copilot",
+    "gen:example": "tsx src/cli/index.ts template generate ./outputs/example --template ./templates/example",
+    "gen:awa": "tsx src/cli/index.ts template generate ./outputs/awa --template ./templates/awa",
+    "gen:awa:this": "tsx src/cli/index.ts template generate . --template ./templates/awa --features copilot",
+    "diff:awa:this": "tsx src/cli/index.ts template diff . --template ./templates/awa --features copilot",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",

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

@@ -82,7 +82,7 @@ example: |
   Enable specific features when generating.
 
   ```bash
-  awa generate --features copilot,claude,cursor
+  awa template generate --features copilot,claude,cursor
   ```
 
   ## Example 3: Custom Template Source
@@ -90,7 +90,7 @@ example: |
   Use a Git repository as the template source.
 
   ```bash
-  awa generate --template owner/repo --features copilot
+  awa template generate --template owner/repo --features copilot
   ```
 
   ## Change Log

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

@@ -113,18 +113,18 @@ example: |
   ### Scenario 1: First-time Setup
 
   A developer starts a new project and wants to add AI agent configuration
-  for GitHub Copilot and Claude. They run `awa generate --features copilot,claude`
+  for GitHub Copilot and Claude. They run `awa template generate --features copilot,claude`
   and get a complete set of configuration files tailored to those two agents.
 
   ### Scenario 2: Adding a New Agent
 
   An existing project already has Copilot configuration. The developer adds
-  Cursor support by running `awa generate --features copilot,cursor`. The engine
+  Cursor support by running `awa template generate --features copilot,cursor`. The engine
   merges the new feature without disrupting existing configuration.
 
   ### Scenario 3: Previewing Changes
 
-  Before applying changes, the developer runs `awa diff` to see what files
+  Before applying changes, the developer runs `awa template diff` to see what files
   would be added, modified, or removed. This gives confidence before committing.
 
   ## Background

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

@@ -100,13 +100,13 @@ example: |
 
   ```bash
   # Generate configuration from default template
-  awa generate
+  awa template generate
 
   # Generate with specific features enabled
-  awa generate --features typescript,testing
+  awa template generate --features typescript,testing
 
   # Preview changes without writing files
-  awa diff
+  awa template diff
   ```
 
   ### Examples
@@ -114,7 +114,7 @@ example: |
   #### Custom Template
 
   ```bash
-  awa generate --template ./my-templates --output ./.ai
+  awa template generate --template ./my-templates --output ./.ai
   ```
 
   ## Documentation

package/templates/awa/_README.md

@@ -6,18 +6,18 @@ This template set generates the awa agent files for all major AI coding tools.
 
 ```bash
 # Interactive tool selection (prompts when no tool flag provided)
-npx awa generate . --template ./templates/awa
+npx awa template generate . --template ./templates/awa
 
 # Single tool
-npx awa generate . --template ./templates/awa --features copilot
-npx awa generate . --template ./templates/awa --features claude
-npx awa generate . --template ./templates/awa --features cursor
+npx awa template generate . --template ./templates/awa --features copilot
+npx awa template generate . --template ./templates/awa --features claude
+npx awa template generate . --template ./templates/awa --features cursor
 
 # Multiple tools
-npx awa generate . --template ./templates/awa --features copilot claude cursor
+npx awa template generate . --template ./templates/awa --features copilot claude cursor
 
 # Cross-tool AGENTS.md only
-npx awa generate . --template ./templates/awa --features agents-md
+npx awa template generate . --template ./templates/awa --features agents-md
 ```
 
 ## Tool Feature Flags
@@ -84,4 +84,4 @@ Shared content is in `_partials/`:
 1. Copy `templates/awa/` to your project
 2. Modify `_partials/awa.core.md` for shared system instruction changes
 3. Modify individual `_partials/awa.*.md` for skill-specific changes
-4. Run `npx awa generate . --features <tool>` to regenerate
+4. Run `npx awa template generate . --features <tool>` to regenerate

package/templates/awa/_partials/awa.core.md

@@ -87,7 +87,7 @@ Markers create the trace, not file paths.
 </traceability_chain>
 
 <file_size_limits>
-Any file exceeding 500 lines MUST be split logically into multiple files unless impossible.
+Any file exceeding schema defined line-limit, or otherwise 500 lines, MUST be split logically into multiple files unless impossible. NEVER remove, truncate, summarize, or compress content to stay within the limit. Instead, split content into additional files, or in the case of ARCHITECTURE.md, push details to other spec files.
 </file_size_limits>
 
 <core_principles>
@@ -111,4 +111,12 @@ All `awa` commands in these instructions assume this resolution.
 You SHALL run `awa check --spec-only` after creating or modifying any file in `.awa/specs/`, `.awa/tasks/`, or `.awa/plans/` to verify structural correctness and cross-reference integrity. Fix any errors before proceeding.
 You SHALL run `awa check` (without --spec-only) after implementing code and tests to verify full traceability coverage.
 </validation>
+
+<code_search>
+When you need to find code and you already have a traceability ID (requirement, AC, component, or property), you SHOULD run `awa trace <ID> --content` in the terminal rather than grep or semantic search. `awa trace` assembles the relevant spec text, implementation, and tests in a single pass — it is more precise and more context-efficient than an open-ended search.
+
+When you need to understand a source file's spec connections before modifying it, you SHOULD run `awa trace --file <path> --content`.
+
+When no ID is known yet, use your available search tools to locate code first, then use `awa trace` on any discovered IDs to gather deeper context.
+</code_search>
 </awa>

package/templates/awa/_partials/awa.usage.md

@@ -103,9 +103,9 @@ awa may be installed locally. Detect the package manager and use the appropriate
     pnpm:    pnpm exec awa <command>
     bun:     bunx awa <command>
 
-### awa init [output] / awa generate [output]
+### awa init [output] / awa template generate [output]
 
-Generate configuration files from templates. `init` and `generate` are aliases.
+Generate configuration files from templates. `init` is a top-level convenience command equivalent to `awa template generate`.
 
 | Option | Description |
 |--------|-------------|
@@ -125,7 +125,7 @@ Generate configuration files from templates. `init` and `generate` are aliases.
 | `--json` | JSON output to stdout (implies --dry-run) |
 | `--summary` | Compact one-line counts summary |
 
-### awa diff [target]
+### awa template diff [target]
 
 Compare generated template output against an existing target directory. Exit code 0 = match, 1 = differences.
 
@@ -160,7 +160,29 @@ Check traceability chain integrity and spec schema conformance. Exit code 0 = cl
 
 Checks performed: orphaned markers, uncovered ACs, broken cross-refs, invalid ID format, orphaned specs, schema validation. Config-only options: `schema-dir`, `schema-enabled`, `ignore-markers`, `spec-only`.
 
-### awa test
+### awa trace
+
+Navigate the traceability chain and assemble context from specs, code, and tests. Use this to gather focused context before implementing, refactoring, or reviewing.
+
+    awa trace [ids...] [options]
+
+| Option | Description |
+|--------|-------------|
+| `[ids...]` | Traceability ID(s) to trace (e.g. `FEAT-1`, `FEAT-1_AC-2`, `FEAT_P-3`) |
+| `--all` | Trace all known IDs in the project |
+| `--scope <code>` | Limit results to a feature code (e.g. `--scope FEAT`) |
+| `--file <path>` | Resolve IDs from a source file's markers — useful to understand a file's spec connections before changing it |
+| `--task <path>` | Resolve IDs from a task file |
+| `--content` | Output actual file sections instead of locations |
+| `--list` | Output file paths only |
+| `--direction <dir>` | Traversal direction: `both` (default), `forward`, `reverse` |
+| `--depth <n>` | Maximum traversal depth |
+| `--no-code` | Exclude source code (spec-only context) |
+| `--no-tests` | Exclude test files |
+| `--json` | JSON output |
+| `-A/-B/-C <n>` | Lines of context after/before/both around a code marker (`--content` only) |
+
+### awa template test
 
 Run template test fixtures. Exit code 0 = all pass, 1 = failures.
 
@@ -172,7 +194,7 @@ Run template test fixtures. Exit code 0 = all pass, 1 = failures.
 
 Discovers `*.toml` fixtures in `_tests/`, renders per fixture, verifies expected files, compares against snapshots.
 
-### awa features
+### awa template features
 
 Discover feature flags available in a template.
 
@@ -237,9 +259,9 @@ Feature resolution order: start with `--features`, expand `--preset` (append, de
 
 Multi-target usage:
 
-    awa generate --all                  # process all targets
-    awa generate --target claude        # process one target
-    awa diff --all                      # diff all targets
+    awa template generate --all                  # process all targets
+    awa template generate --target claude        # process one target
+    awa template diff --all                      # diff all targets
 
 ## Template Sources
 
@@ -258,8 +280,8 @@ Git templates are cached in `~/.cache/awa/templates/`. Use `--refresh` to re-fet
 
 | Command | 0 | 1 | 2 |
 |---------|---|---|---|
-| `awa init` / `awa generate` | Success | — | Internal error |
-| `awa diff` | All files match | Differences found | Internal error |
+| `awa init` / `awa template generate` | Success | — | Internal error |
+| `awa template diff` | All files match | Differences found | Internal error |
 | `awa check` | All checks pass | Errors found | Internal error |
-| `awa test` | All fixtures pass | Failures found | Internal error |
-| `awa features` | Success | Error | — |
+| `awa template test` | All fixtures pass | Failures found | Internal error |
+| `awa template features` | Success | Error | — |