Skip to content

Commit fc59de2

Browse files
ProfRandom92ProfRandom92
committed
docs(phase6): add agy-ct agentic CLI skills
1 parent 9687141 commit fc59de2

4 files changed

Lines changed: 111 additions & 0 deletions

File tree

‎.agent/skills/07_cli_surface.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Skill 07: agy-ct CLI Surface Rules
2+
3+
## 1. CLI Subcommand Taxonomy
4+
`agy-ct` must implement the following subcommand structure exactly:
5+
- `run`
6+
- `demo`
7+
- `doctor`
8+
- `validate`
9+
- `handoff`
10+
- `package`
11+
- `compress`
12+
- `inspect`
13+
- `verify`
14+
- `replay`
15+
- `adversarial`
16+
- `context`
17+
- `build`
18+
- `render`
19+
- `validate`
20+
- `all`
21+
- `schema check`
22+
- `report export`
23+
- `notebook bundle`
24+
25+
## 2. Clap Parser Behavior
26+
- Subcommands must be defined using strict typed options inside Rust's `clap` crate.
27+
- Command-line parsing must enforce correct parameter names, required arguments, and mutually exclusive options at the parser level.
28+
- Clean `-h` and `--help` pages must be auto-generated for each command and subcommand.
29+
30+
## 3. Phase 6B Binary Scope Gating
31+
- Phase 6B is strictly limited to initializing the `agy-ct` binary and constructing the parser tree.
32+
- No execution logic, file operations, or validation pipeline workflows should be implemented in Phase 6B. All subcommands must return placeholder confirmation messages or print structural config layouts when run.
33+
34+
## 4. Preservation of sparkctl
35+
- Under no circumstances should implementation changes to `agy-ct` alter or break any existing command surface or execution behavior of the compatibility CLI binary `sparkctl`.
36+
- Codebase refactoring must maintain backward compatibility.

‎.agent/skills/08_agentic_output_contract.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Skill 08: Agentic Output Contract
2+
3+
## 1. Stdout and Stderr Separation
4+
To facilitate automation and downstream piping by software agents:
5+
- **stdout** is strictly reserved for machine-readable payloads, exported file contents, and structured JSON logs.
6+
- **stderr** is used for interactive human-facing indicators, warnings, logs, diagnostics, and CLI title blocks.
7+
8+
## 2. Structured JSON Output
9+
- When running with `--json` or `--output json`, all command-line outputs, errors, and run steps must be serialized into structured JSON objects on stdout.
10+
- Any output sent to stdout under JSON mode must validate against the target JSON schema.
11+
12+
## 3. Quiet and Plain Configurations
13+
- Under `--plain` or `--json` or `--non-interactive` flags, no ANSI formatting escape codes, progressive spinners, interactive loading lines, or ticker indicators may be printed to stdout or stderr.
14+
- Terminal outputs must remain static and flat in these modes.
15+
16+
## 4. Exit Codes and Compact Error Model
17+
- The binary must propagate specific exit codes on validation failures:
18+
- `0`: Complete success.
19+
- `1`: Unexpected execution error.
20+
- `2`: Validation integrity or leak check failure.
21+
- `3`: Missing configuration files or schema files.
22+
- `4`: Invalid file structure or signature.
23+
- Error outputs must be compact (single-line text) by default. Detailed traces can be requested via `--explain <CODE>` or `--verbose`.
24+
- In non-interactive mode, if input is required, the execution must abort immediately and exit with a non-zero code.
25+
26+
## 5. Security and Leak Limits
27+
- Access keys, environment secrets, and sensitive tokens must never be written to JSON reports, stdout, or stderr logs.

‎.agent/skills/09_phase6_implementation_gate.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Skill 09: Phase 6 Implementation Gates
2+
3+
## 1. Phased Execution Roadmap
4+
No cross-phase implementations are allowed. Development must follow these strict gates:
5+
- **Phase 6B**: `agy-ct` binary configuration, dependencies registration, and `clap` tree definition only. No execution logic.
6+
- **Phase 6C**: Compatibility command wrappers implementation (mapping `doctor`, `validate`, and `handoff` commands).
7+
- **Phase 6D**: Automatic `run` and `demo` workflow orchestrator logic.
8+
- **Phase 6E**: Structured output modes (`--json`, `--plain`) and execution JSON report exporter.
9+
- **Phase 6F**: Context cache valve functionality and notebook bundle exporter.
10+
11+
## 2. Dependency Restriction
12+
- The installation of heavy or complex libraries (`dag_exec`, `asupersync`, `wasm_sandbox`, `wasmtime`, `tokio`, `ratatui`) is deferred for future phases.
13+
- No new packages or dependencies may be registered in `Cargo.toml` without explicit phase-gate approval.
14+
15+
## 3. Safety and Sandbox Bounds
16+
- **Offline Operations**: By default, no subcommands may access the network.
17+
- **Git Safety**: CLI commands must never run git commits or push operations.
18+
- **No Destructive Overwrites**: Commands must prompt before overwriting files unless overridden by `--non-interactive` or `--force`.
19+
- **Directory Bounds**: Commands must restrict all scans to the workspace directory. No parent or sibling directory searches are permitted.

‎PHASE6A1_AGY_CT_AGENTIC_CLI_SKILLS_SNAPSHOT.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Phase 6A.1 agy-ct Agentic CLI Skills Snapshot
2+
3+
## 1. Files Created
4+
- [.agent/skills/07_cli_surface.md](file:///C:/Users/contr/sandbox_workspace/Antigravity-Comptextv7-unified/git_post_push_verification/repo/.agent/skills/07_cli_surface.md)
5+
- [.agent/skills/08_agentic_output_contract.md](file:///C:/Users/contr/sandbox_workspace/Antigravity-Comptextv7-unified/git_post_push_verification/repo/.agent/skills/08_agentic_output_contract.md)
6+
- [.agent/skills/09_phase6_implementation_gate.md](file:///C:/Users/contr/sandbox_workspace/Antigravity-Comptextv7-unified/git_post_push_verification/repo/.agent/skills/09_phase6_implementation_gate.md)
7+
8+
## 2. Purpose of Each Skill
9+
- **Skill 07 (agy-ct CLI Surface)**: Establishes rules for the CLI subcommand structure, parser validation, and preservation of the legacy `sparkctl` binary.
10+
- **Skill 08 (Agentic Output Contract)**: Sets the guidelines for stdout/stderr separation, output formatting (JSON, plain, quiet), exit code mapping, and security requirements.
11+
- **Skill 09 (Phase 6 Implementation Gates)**: Structures the roadmap into phases, controls external dependency updates, and outlines safety limits for network and workspace directory traversal.
12+
13+
## 3. Forbidden Scope Confirmation
14+
- Verified that no Rust code implementation has been added.
15+
- Verified `Cargo.toml` remains unchanged, and no new dependencies have been installed.
16+
- Verified that no integration or unit tests were modified.
17+
- Verified `README.md` has not been edited.
18+
- No image or repository assets were added.
19+
- GitHub Actions workflow configurations remain unchanged.
20+
- No network operations or git commits/pushes were run.
21+
- `POST_PUSH_GITHUB_VERIFICATION.md` remains untracked and unstaged.
22+
23+
## 4. Safety & Leak Boundaries
24+
- Offline behavior was deterministic in the validated test scope.
25+
- Configured leak checks passed in the validated scope.
26+
- No blocking risks found in the validated scope.
27+
28+
## 5. Next Recommended Phase
29+
- Begin Phase 6B (agy-ct binary initialization and clap command tree setup) only after approval.

0 commit comments

Comments
 (0)