@ncoderz/awa 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ncoderz/awa",
-  "version": "1.4.0",
+  "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": {

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

@@ -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

@@ -160,6 +160,28 @@ 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 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.