@chinhae/atw-cli 0.1.0

package/dist/templates/common/bundled-skills/atw-spec/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: atw-spec
+description: "将当前的讨论内容整理成一份需求规格说明书，并发布到项目问题跟踪系统中——无需进行访谈，只需对已讨论的内容进行总结即可。"
+disable-model-invocation: true
+---
+
+This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user — just synthesize what you already know.
+
+The issue tracker and triage label vocabulary should have been provided to you. If not, tell the user to call the Skill tool for `atw-init-repo`, which writes both.
+
+## Process
+
+1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching.
+
+2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.
+
+Check with the user that these seams match their expectations.
+
+3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.
+
+<spec-template>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this spec.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</spec-template>

package/dist/templates/common/bundled-skills/atw-spec/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Oxyteam Spec"
+  short_description: "将对话转化为技术规格书"
+policy:
+  allow_implicit_invocation: false

package/dist/templates/common/bundled-skills/atw-spec-bootstrap/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: atw-spec-bootstrap
+description: "Bootstrap project-specific ATW coding specs with a platform-neutral single-agent workflow. Use when creating or refreshing .atw/spec guidelines, analyzing a codebase with GitNexus, ABCoder, or source inspection, decomposing package/layer spec work, and writing real codebase-backed spec docs without placeholder text."
+---
+
+# ATW Spec Bootstrap
+
+Use this skill to create or refresh `.atw/spec/` guidelines from the real codebase. One capable agent owns the full loop: analyze the repository, choose the spec boundaries, write the docs, and verify the result. The workflow does not depend on a specific host, CLI, or agent brand.
+
+## Workflow
+
+1. Confirm ATW is initialized and inspect the current `.atw/spec/` tree.
+2. Analyze the repository architecture with the best available tools: GitNexus, ABCoder, language tooling, and direct source reads.
+3. Decompose the spec work by package and layer only when that reflects the actual codebase.
+4. Fill or reshape the spec files with concrete patterns, file paths, examples, and anti-patterns from the project.
+5. Verify that the final specs are internally consistent and contain no template placeholders.
+
+## Reference Routing
+
+| Need | Read |
+|------|------|
+| Repository architecture analysis | [references/repository-analysis.md](references/repository-analysis.md) |
+| Spec work decomposition and task planning | [references/spec-task-planning.md](references/spec-task-planning.md) |
+| Writing high-signal ATW spec files | [references/spec-writing.md](references/spec-writing.md) |
+| GitNexus and ABCoder MCP setup | [references/mcp-setup.md](references/mcp-setup.md) |
+
+## Operating Rules
+
+- Treat templates as starting points, not contracts. Delete, rename, split, or add spec files when the repository calls for it.
+- Prefer source-backed rules over generic advice. Every important recommendation should point at a real file or repeated local pattern.
+- Keep execution single-owner by default. Optional helper agents are an implementation detail, not a requirement or user-visible dependency.
+- Do not write platform-specific instructions unless the target project already standardizes on that platform.
+- Do not leave placeholder text, empty headings, or copied boilerplate in `.atw/spec/`.
+
+## Done Criteria
+
+- `.atw/spec/` describes the project as it exists now.
+- Each relevant package or layer has practical coding guidance with real examples.
+- Non-applicable template sections are removed.
+- `index.md` files match the final spec file set.
+- Any required setup or analysis assumptions are documented in the relevant spec or task notes.

package/dist/templates/common/bundled-skills/atw-spec-bootstrap/references/mcp-setup.md

@@ -0,0 +1,90 @@
+# MCP Setup
+
+GitNexus and ABCoder are recommended when bootstrapping ATW specs because they expose architecture and AST context to the agent. They are tool choices, not platform requirements. Configure them through whatever MCP mechanism your agent host provides.
+
+## GitNexus
+
+GitNexus builds a code knowledge graph from the repository. Use it for module boundaries, execution flows, dependency relationships, blast radius, and graph queries.
+
+### Install and Index
+
+```bash
+# Run from the repository root.
+npx gitnexus analyze
+
+# Check index status.
+npx gitnexus status
+
+# Re-index after code changes when the analysis is stale.
+npx gitnexus analyze
+```
+
+The index is written to `.gitnexus/`. Keep embeddings only if the project already uses them; otherwise a normal index is enough for spec bootstrapping.
+
+### MCP Server Command
+
+Use this server command in the host's MCP configuration:
+
+```bash
+npx -y gitnexus mcp
+```
+
+### Useful Tools
+
+| Tool | Purpose |
+|------|---------|
+| `gitnexus_query` | Find execution flows and functional areas by concept |
+| `gitnexus_context` | Inspect callers, callees, references, and process participation for a symbol |
+| `gitnexus_impact` | Understand blast radius before changing a symbol |
+| `gitnexus_detect_changes` | Check changed symbols and affected flows before finishing |
+| `gitnexus_cypher` | Run direct graph queries |
+| `gitnexus_list_repos` | List indexed repositories |
+
+## ABCoder
+
+ABCoder parses code into UniAST and gives precise package, file, and node-level structure. Use it for signatures, type shapes, implementations, dependencies, and reverse references.
+
+### Install
+
+```bash
+go install github.com/cloudwego/abcoder@latest
+abcoder --help
+```
+
+### Parse Repositories
+
+```bash
+abcoder parse /absolute/path/to/package \
+  --lang typescript \
+  --name package-name \
+  --output ~/abcoder-asts
+```
+
+For monorepos, parse each package with a stable `--name` so task notes can reference the same repository names.
+
+### MCP Server Command
+
+Use this server command in the host's MCP configuration:
+
+```bash
+abcoder mcp ~/abcoder-asts
+```
+
+### Useful Tools
+
+| Tool | Layer | Purpose |
+|------|-------|---------|
+| `list_repos` | 1 | List parsed repositories |
+| `get_repo_structure` | 2 | Inspect packages and files |
+| `get_package_structure` | 3 | Inspect nodes within a package |
+| `get_file_structure` | 3 | Inspect functions, classes, types, and signatures in a file |
+| `get_ast_node` | 4 | Retrieve code, dependencies, references, and implementations |
+
+## Verification
+
+After configuration, verify from the agent host that both MCP servers are visible. Then run one simple query against each server before starting the spec writing pass.
+
+```bash
+ls .gitnexus/meta.json
+ls ~/abcoder-asts/*.json
+```

package/dist/templates/common/bundled-skills/atw-spec-bootstrap/references/repository-analysis.md

@@ -0,0 +1,59 @@
+# Repository Analysis
+
+The goal is to discover the project's real architecture before writing rules. Do not start from generic spec templates and fill blanks. Start from the code, then let the spec structure follow.
+
+## Analysis Order
+
+1. Read the existing `.atw/spec/` tree and note which files are templates, outdated, or already project-specific.
+2. Inspect package manifests, build scripts, workspace config, and top-level documentation to identify packages and runtime layers.
+3. Use GitNexus for execution flows, module clusters, dependency hubs, and impact-sensitive areas.
+4. Use ABCoder or language-native tooling for exact signatures, types, class boundaries, and implementation examples.
+5. Read representative source and test files directly before turning any finding into a spec rule.
+
+## What To Capture
+
+| Area | Questions |
+|------|-----------|
+| Package boundaries | What does each package own? What imports cross boundaries? |
+| Runtime layers | Which code is CLI, backend, frontend, worker, shared library, test-only, or tooling? |
+| Core abstractions | Which types, services, stores, commands, routes, or adapters define the system shape? |
+| Data flow | Where does user input enter, how is it validated, and where does state persist? |
+| Error handling | How are failures represented, logged, surfaced, and tested? |
+| Configuration | Where do defaults, environment config, generated files, and templates live? |
+| Tests | Which test styles are trusted examples for new work? |
+
+## GitNexus Usage
+
+Start broad, then inspect specific symbols:
+
+```text
+gitnexus_query({query: "CLI command execution flow"})
+gitnexus_query({query: "template generation and migration"})
+gitnexus_context({name: "SymbolName"})
+gitnexus_cypher({query: "MATCH (n)-[r]->(m) RETURN n.name, type(r), m.name LIMIT 30"})
+```
+
+Use GitNexus results to find important files and flows. Do not quote graph output as the final authority until you have checked the relevant source files.
+
+## ABCoder Usage
+
+Use ABCoder when the spec needs exact code shapes:
+
+```text
+list_repos()
+get_repo_structure({repo_name: "package-name"})
+get_file_structure({repo_name: "package-name", file_path: "src/example.ts"})
+get_ast_node({repo_name: "package-name", node_ids: [{mod_path: "...", pkg_path: "...", name: "SymbolName"}]})
+```
+
+ABCoder is most valuable for documenting constructor patterns, function signatures, type contracts, and reference chains.
+
+## Analysis Notes
+
+Keep short notes while analyzing. The notes should include:
+
+- Package or layer name.
+- Files that define the local pattern.
+- Rules the spec should teach.
+- Anti-patterns found in old code, comments, tests, or migration paths.
+- Spec files that should be created, deleted, renamed, or merged.

package/dist/templates/common/bundled-skills/atw-spec-bootstrap/references/spec-task-planning.md

@@ -0,0 +1,61 @@
+# Spec Task Planning
+
+Use a single agent as the default execution model. The agent may create ATW tasks for traceability, but the skill should not require a specific platform, CLI, or parallel worker model.
+
+## Decomposition
+
+Create spec work units around real ownership boundaries:
+
+- One package when a package has its own conventions.
+- One layer when the same package has distinct frontend, backend, CLI, worker, or shared-library rules.
+- One cross-cutting guide when a pattern spans packages and is not owned by one layer.
+
+Avoid artificial decomposition. A small library usually needs one focused spec pass, not several tasks.
+
+## Task Shape
+
+When an ATW task is useful, write a concise PRD with these sections:
+
+```markdown
+# Fill <package-or-layer> ATW Specs
+
+## Goal
+Write project-specific `.atw/spec/` guidance for <scope>.
+
+## Scope
+- Spec directory:
+- Source directories to inspect:
+- Tests to inspect:
+- Out of scope:
+
+## Architecture Context
+Summarize the concrete findings from repository analysis.
+
+## Files To Create Or Update
+- `.atw/spec/.../index.md`
+- `.atw/spec/.../<topic>.md`
+
+## Rules
+- Adapt the spec file set to the real codebase.
+- Use real source examples with file paths.
+- Remove template-only sections that do not apply.
+- Do not modify product source code unless the task explicitly asks for it.
+
+## Acceptance Criteria
+- [ ] Specs contain concrete examples and anti-patterns from the repository.
+- [ ] No placeholder text remains.
+- [ ] Index files match the final spec files.
+- [ ] Claims are backed by source files, tests, or project docs.
+```
+
+## Optional Helper Agents
+
+If the host supports subagents, helpers can inspect independent packages or run verification. They are optional. The main agent still owns integration and final quality.
+
+Helper tasks must have clear ownership:
+
+- Read-only research tasks may inspect any source needed for the assigned scope.
+- Write tasks should own disjoint spec directories.
+- Verification tasks should check placeholder removal, broken links, and consistency.
+
+Do not encode helper-agent names, vendor-specific commands, or platform-specific routing in the skill. Put only the required work and acceptance criteria in the task.

package/dist/templates/common/bundled-skills/atw-spec-bootstrap/references/spec-writing.md

@@ -0,0 +1,70 @@
+# Spec Writing
+
+ATW specs are coding guidance for future agents. They should explain how to work in this repository, not how a generic project might be organized.
+
+## Write From Evidence
+
+Each important rule should be backed by one of these:
+
+- A source file that demonstrates the preferred pattern.
+- A test file that shows expected behavior.
+- A project document that defines the convention.
+- A repeated pattern across multiple files.
+
+Use short snippets only when they make the rule clearer. Prefer linking to the file path and naming the symbol or behavior.
+
+## File Structure
+
+Keep the spec tree aligned with the project:
+
+- Keep `index.md` as the navigation file for the spec directory.
+- Split topics when developers would look for them independently.
+- Merge topics when separate files would repeat the same rule.
+- Delete template files that do not apply.
+- Add new files for important local patterns the template missed.
+
+## Content Standards
+
+Good spec sections include:
+
+- When the rule applies.
+- The local pattern to follow.
+- The source or test files that prove the pattern.
+- Common mistakes or anti-patterns.
+- Verification commands or checks when they are specific and reliable.
+
+Avoid:
+
+- Placeholder prose.
+- Generic framework advice.
+- Tool instructions that only work in one agent host.
+- Long copied code blocks.
+- Rules based on a single accidental implementation detail.
+
+## Example Shape
+
+```markdown
+## Command Handlers
+
+Command handlers should keep argument parsing, validation, and side effects separate. The local pattern is:
+
+- Parse CLI flags at the command boundary.
+- Convert raw inputs into typed task options before invoking core logic.
+- Keep filesystem writes in the command or service layer, not in template helpers.
+
+Reference files:
+- `packages/cli/src/commands/example.ts`
+- `packages/cli/test/commands/example.test.ts`
+
+Avoid passing raw `process.argv` or unvalidated config objects into shared helpers.
+```
+
+## Final Pass
+
+Before finishing:
+
+```bash
+grep -R "To be filled\\|TODO: fill\\|placeholder" .atw/spec
+```
+
+Also check links, index files, and whether any spec still describes a template rather than this repository.

package/dist/templates/common/bundled-skills/atw-tdd/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: atw-tdd
+description: "测试驱动开发。当用户希望采用“先测试后开发”的方式构建功能或修复缺陷、提及“红-绿-重构”原则，或者需要集成测试时，可采用此方法。"
+---
+
+# Test-Driven Development
+
+TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle — consult them before and during the loop, not after.
+
+When exploring the codebase, read `CONTEXT.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.
+
+## What a good test is
+
+Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists — and survives refactors because it doesn't care about internal structure.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Seams — where tests go
+
+A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.
+
+**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything — agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.
+
+Ask: "What's the public interface, and which seams should we test?"
+
+When the shape of that interface is itself in question — how deep the module is, where the seam belongs, what the interface should expose — call the Skill tool with "atw-codebase-design" for the vocabulary. It is the shared source of the module, interface, depth, seam, adapter, leverage and locality terms, and it is a reference to consult, not a session to run.
+
+## Anti-patterns
+
+- **Implementation-coupled** — mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.
+- **Tautological** — the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth — a known-good literal, a worked example, the spec.
+- **Horizontal slicing** — writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead — one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you.
+
+## Rules of the loop
+
+- **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
+- **One slice at a time.** One seam, one test, one minimal implementation per cycle.
+- **Refactoring is not part of the loop.** It belongs to the review stage (see the `atw-code-review` skill), not the red → green implementation cycle.

package/dist/templates/common/bundled-skills/atw-tdd/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Oxyteam TDD"
+  short_description: "测试驱动的红-绿-重构"

package/dist/templates/common/bundled-skills/atw-tdd/mocking.md

@@ -0,0 +1,59 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes - prefer test DB)
+- Time/randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes/modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+**1. Use dependency injection**
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+**2. Prefer SDK-style interfaces over generic fetchers**
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint

package/dist/templates/common/bundled-skills/atw-tdd/tests.md

@@ -0,0 +1,77 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```
+
+**Tautological tests**: Expected value restates the implementation, so the test passes by construction.
+
+```typescript
+// BAD: Expected value is recomputed the way the code computes it
+test("calculateTotal sums line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, i) => sum + i.price, 0);
+  expect(calculateTotal(items)).toBe(expected);
+});
+
+// GOOD: Expected value is an independent, known literal
+test("calculateTotal sums line items", () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
+});
+```