Metadata-Version: 2.4
Name: ana-and-new-team
Version: 0.2.0
Summary: Slash-command-driven MCP server with Ana and team (Cham, Ark, Fey, Bud, Tess) for Jakarta EE (koseiin-*) delivery.
Author: ana-and-new-team authors
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: anyio>=4.3
Requires-Dist: mcp>=1.2.0
Requires-Dist: openpyxl>=3.1.2
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: pydantic>=2.6
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# ana-and-new-team

[![PyPI version](https://img.shields.io/pypi/v/ana-and-new-team.svg)](https://pypi.org/project/ana-and-new-team/)
[![Python](https://img.shields.io/pypi/pyversions/ana-and-new-team.svg)](https://pypi.org/project/ana-and-new-team/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Slash-command-driven MCP server that turns Excel design specs into a coordinated
development pipeline for the **koseiin-\*** Jakarta EE / WildFly stack.

Six file-bus agents — **Ana** (Analyzer), **Cham** (QA), **Ark** (Architect),
**Fey** (Frontend), **Bud** (Backend), **Tess** (Tester) — collaborate via
artifacts under `.ant-context/`. The server itself is host-agnostic; it speaks
MCP stdio and works with **Claude Code**, **opencode**, and **Cline**.

> Windows-first. The deploy gate calls `domain.bat`. A cross-OS code path is
> retained for development on macOS / Linux but production usage is Windows.

* **Source:** <https://gitlab.enlinka.co/work-project/ana-and-new-team>
* **Issues:** <https://gitlab.enlinka.co/work-project/ana-and-new-team/-/issues>
* **PyPI:** <https://pypi.org/project/ana-and-new-team/>

---

## What it does

Three slash commands, all delivered as MCP **prompts**:

| Slash command         | Purpose                                                                       |
| --------------------- | ----------------------------------------------------------------------------- |
| `/ant-new-screen`     | New screen from design Excels. Halts if プログラム設計書(簡易) is not attached. |
| `/ant-new-ita`        | ITA (issue-tracker) fix. Each Ana finding = code-issue / root-cause / solution / why-resolves. |
| `/ant-change-request` | CR analysis + impact + delivery plan.                                          |

Every pipeline:

1. **Reads every sheet of every attached `.xlsx`** — never samples.
2. **Drops strikethrough text** from analysis (cell *and* run level), but logs it.
3. **Resolves dependency jars** through `pom.xml` → `~/.m2/repository/...`.
4. **Halts at the deploy gate** if WildFly is unreachable or `target/*.war` is missing,
   surfacing the exact `mvn` / `domain.bat` commands the user must approve.
5. **Routes work to six personas** via a `DispatchPlan` keyed by file paths under `.ant-context/`.
6. **Versions every revision** with an `-r{N}` suffix so re-runs never clobber prior work.

---

## Quick install

Once `ana-and-new-team` is on PyPI, the fastest path is:

```bat
uvx ana-and-new-team install --all
```

That single command:

1. Detects which AI hosts (**Claude Code**, **opencode**, **Cline**) are
   installed on this machine.
2. Patches their config files in place (atomic write, `.bak` left next to the
   original) — never touching other servers' blocks. The edit is surgical: your
   existing keys, `// comments`, and formatting are preserved byte-for-byte, and
   only the `ana-and-new-team` block is added or removed. For opencode it updates
   your existing config — `opencode.jsonc`, `opencode.json`, `config.jsonc`, or
   `config.json` — rather than creating a duplicate file.
3. Registers the server's launch command as `uvx ana-and-new-team`, so each
   host always pulls the latest published wheel.

To inspect what *would* change without touching disk:

```bat
uvx ana-and-new-team install --all --dry-run
```

To overwrite an existing — but different — block:

```bat
uvx ana-and-new-team install --all --force
```

To uninstall just our block from every host:

```bat
uvx ana-and-new-team uninstall --all
```

You can scope to a single host with `--host claude-code`, `--host opencode`,
or `--host cline` (repeatable; mutually exclusive with `--all`).

## Windows install

`ana-and-new-team` is the same Python package on every OS, but the bootstrap
on Windows is different from macOS/Linux because Windows ships neither Python
nor `uv` by default. Pick **one** of the three paths below.

### Path A — `uv` + `uvx` (recommended)

This mirrors the macOS quick-install flow exactly. `uvx` fetches the latest
published wheel into a temporary, isolated environment each run, so you never
have to manage a venv yourself.

1. Open **PowerShell** (regular, not elevated) and install `uv`:

   ```powershell
   powershell -ExecutionPolicy Bypass -c "irm https://astral.sh/uv/install.ps1 | iex"
   ```

   Close and reopen PowerShell so the new `PATH` entry is picked up. Verify:

   ```powershell
   uv --version
   uvx --version
   ```

2. Install / register:

   ```powershell
   uvx ana-and-new-team install --all
   ```

3. Sanity-check:

   ```powershell
   uvx ana-and-new-team --version
   uvx ana-and-new-team doctor
   ```

The `install` subcommand will detect whichever of **Claude Code**,
**opencode**, **Cline** are present and patch each one's config file.
The launch command written into those configs will be
`uvx ana-and-new-team`, so every restart of your AI host pulls the latest
published wheel.

### Path B — `pipx` (persistent, no Python knowledge required)

Use this if you'd rather have one stable copy of the binary on disk instead
of `uvx` resolving on every launch.

1. Install Python 3.10 or newer from <https://www.python.org/downloads/windows/>.
   On the installer, tick **Add python.exe to PATH**.
2. Install `pipx` and put it on PATH:

   ```powershell
   py -m pip install --user pipx
   py -m pipx ensurepath
   ```

   Close and reopen PowerShell.
3. Install the package:

   ```powershell
   pipx install ana-and-new-team
   ```

4. Register with your AI hosts:

   ```powershell
   ana-and-new-team install --all
   ```

   With this path the command written into host configs is the absolute path
   of `ana-and-new-team.exe` under `%USERPROFILE%\.local\bin\` (or wherever
   pipx put it). To stay on the latest version run `pipx upgrade ana-and-new-team`.

### Path C — Editable clone (contributors)

For local development against the source tree:

```powershell
git clone https://gitlab.enlinka.co/work-project/ana-and-new-team.git
cd ana-and-new-team
py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .[dev]
ana-and-new-team --version
pytest -q
```

To wire up an AI host against this checkout (no PyPI hop):

```powershell
ana-and-new-team install --all --command "uvx --from C:\path\to\ana-and-new-team ana-and-new-team"
```

### Where Windows host configs actually live

The `install` subcommand finds these automatically; the table is here so you
can hand-edit or troubleshoot.

| Host        | Config path on Windows                                  |
| ----------- | ------------------------------------------------------- |
| Claude Code | `%USERPROFILE%\.claude.json`                            |
| opencode    | `%APPDATA%\opencode\opencode.json`                      |
| Cline       | `%APPDATA%\Code\User\settings.json` (VS Code's settings)|

### Windows-specific gotchas

- **Backslashes in env vars must be escaped inside JSON.** Use `C:\\src\\koseiin-common`
  (or forward slashes — Windows accepts both in `pathlib`).
- **WildFly's `domain.bat` is hard-coded into the deploy gate** for Windows.
  Set `ANT_JBOSS_HOME` to the install root (e.g. `C:\wildfly-31.0.0.Final`),
  not to the `bin\` directory.
- **PowerShell vs. cmd quoting differs.** The examples above use PowerShell.
  In `cmd.exe`, `--command` arguments containing spaces should be wrapped in
  double quotes the same way.
- **Long-path support.** If your koseiin checkouts are deep, enable long
  paths in Windows (`gpedit` → *Computer Configuration → Administrative
  Templates → System → Filesystem → Enable Win32 long paths*). The Maven and
  jar-inspection code paths handle long paths correctly once the OS allows them.
- **Antivirus / Defender on first run** can briefly delay `uvx`'s extraction
  step. The first `uvx ana-and-new-team install --all` may take 30+ seconds;
  subsequent runs are cached.

### Verifying everything works

```powershell
ana-and-new-team doctor
ana-and-new-team inspect
```

`doctor` prints environment + persona + path-tool + host-detection report.
`inspect` connects to the server in-process and lists the 8 tools, 3
prompts, and 7 persona resources.

## Install (manual)

Requires Python 3.10+.

### With `pipx`

```bat
pipx install ana-and-new-team
```

### With `uv tool`

```bat
uv tool install ana-and-new-team
```

### From a clone (development)

```bat
git clone https://gitlab.enlinka.co/work-project/ana-and-new-team.git
cd ana-and-new-team
pip install -e .[dev]
```

After install, the `ana-and-new-team` console script is on PATH. Subcommands:

| Command                              | Purpose                                                              |
| ------------------------------------ | -------------------------------------------------------------------- |
| `ana-and-new-team` (no args)         | Run the MCP server over stdio (default).                              |
| `ana-and-new-team serve`             | Same as above, explicit.                                              |
| `ana-and-new-team install [--all]`   | Patch host configs. `--dry-run`, `--force`, `--command "<cmd>"`.      |
| `ana-and-new-team uninstall [--all]` | Remove our block from host configs. `--dry-run`.                      |
| `ana-and-new-team doctor`            | Read-only diagnostic. `--json` for machine-readable output.           |
| `ana-and-new-team inspect`           | Enumerate exposed tools/prompts/resources. `--json` supported.        |

---

## Register with your AI host (manual fallback)

If you can't (or don't want to) use `install`, register manually.

### Claude Code

```bat
claude mcp add ana-and-new-team -- ana-and-new-team
```

Slash commands appear as `/ant-new-screen`, `/ant-new-ita`, `/ant-change-request`.

### opencode

Edit `%USERPROFILE%\.config\opencode\opencode.json`:

```json
{
  "mcp": {
    "servers": {
      "ana-and-new-team": {
        "command": "ana-and-new-team",
        "args": [],
        "env": {
          "ANT_JBOSS_HOME": "C:\\wildfly-31.0.0.Final",
          "ANT_KOSEIIN_REPOS": "koseiin-common=C:\\src\\koseiin-common,koseiin-dao=C:\\src\\koseiin-dao,koseiin-backend=C:\\src\\koseiin-backend,koseiin-frontend=C:\\src\\koseiin-frontend"
        }
      }
    }
  }
}
```

### Cline (VS Code)

In VS Code settings (`Cline > MCP Servers`):

```json
{
  "cline.mcpServers": {
    "ana-and-new-team": {
      "transport": "stdio",
      "command": "ana-and-new-team",
      "args": [],
      "env": {
        "ANT_JBOSS_HOME": "C:\\wildfly-31.0.0.Final",
        "ANT_KOSEIIN_REPOS": "koseiin-common=C:\\src\\koseiin-common,koseiin-dao=C:\\src\\koseiin-dao,koseiin-backend=C:\\src\\koseiin-backend,koseiin-frontend=C:\\src\\koseiin-frontend"
      }
    }
  }
}
```

---

## Configuration

| Variable                  | Required                                              | Default                       | Purpose                                                                 |
| ------------------------- | ----------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------------- |
| `ANT_CONTEXT_ROOT`        | no                                                    | `./.ant-context`              | File-bus root. Personas, analysis, QA, architecture, cache live here.   |
| `ANT_JBOSS_HOME`          | **yes** for `/ant-new-screen` and `/ant-change-request` | —                             | Path to WildFly/JBoss. Deploy gate calls `${ANT_JBOSS_HOME}/bin/domain.bat`. |
| `ANT_JBOSS_URL`           | no                                                    | `http://localhost:9990`       | Health probe. Gate is **ready** when this responds 2xx-4xx within 2 s. |
| `ANT_KOSEIIN_REPOS`       | **yes** for `/ant-new-screen` and `/ant-change-request` | —                             | Deploy targets. See **Repo map format** below.                          |
| `ANT_QA_MAX_ROUNDS`       | no                                                    | `6`                           | Hard cap on Ana ⇄ Cham debate rounds.                                   |
| `ANT_DECOMPILER`          | no                                                    | unset                         | `cfr` or `procyon`. If set, koseiin-\* jar deep-scans run a decompile.  |
| `ANT_JAR_DEEPSCAN_ALL`    | no                                                    | `0`                           | `1` to deep-scan **every** jar (default: only those whose group/artifactId starts with `koseiin`). |
| `MAVEN_REPO_LOCAL`        | no                                                    | `~/.m2/repository`            | Override local Maven repo. `<localRepository>` in `~/.m2/settings.xml` is also honored automatically. |

> **`ANT_KOSEIIN_ROOTS` is not used.** Earlier drafts referenced it; it has been
> removed entirely. Source jars come from `pom.xml` → `~/.m2/`. Build/deploy
> targets come from `ANT_KOSEIIN_REPOS`.

### Repo map format (`ANT_KOSEIIN_REPOS`)

All four keys are required: `koseiin-common`, `koseiin-dao`, `koseiin-backend`, `koseiin-frontend`.
Each value must be an existing directory containing a `pom.xml`.

**Comma list (recommended for env vars on Windows):**

```
koseiin-common=C:\src\koseiin-common,koseiin-dao=C:\src\koseiin-dao,koseiin-backend=C:\src\koseiin-backend,koseiin-frontend=C:\src\koseiin-frontend
```

**JSON (auto-detected by leading `{`):**

```json
{"koseiin-common":"C:\\src\\koseiin-common","koseiin-dao":"C:\\src\\koseiin-dao","koseiin-backend":"C:\\src\\koseiin-backend","koseiin-frontend":"C:\\src\\koseiin-frontend"}
```

Validation runs at deploy-gate entry, **not** at server startup — so the server
keeps running for read-only inspection commands even when the deploy
prerequisites are missing.

---

## Deploy gate

`/ant-new-screen` and `/ant-change-request` consult the gate **before** any
agent writes architecture. The gate is *evaluative*: it returns a structured
directive listing the exact commands the user must approve. **It never auto-runs.**

Order is fixed:

1. **Start WildFly/JBoss in domain mode** — `${ANT_JBOSS_HOME}\bin\domain.bat`
   (skipped if `ANT_JBOSS_URL` already responds).
2. `mvn clean install` in `koseiin-common`.
3. `mvn clean install` in `koseiin-dao`.
4. `mvn clean wildfly:deploy` in `koseiin-backend`.
5. `mvn clean wildfly:deploy` in `koseiin-frontend`.
6. **Optional**, always offered: `mvn dependency:sources -q` in the active
   workspace — pulls koseiin-\* source jars into `~/.m2` so Bud and Fey can
   inspect real method bodies, not just constant pools.

Steps 2–5 are emitted only when `target/*.war` is missing in `koseiin-backend`
or `koseiin-frontend`.

The host model surfaces the directive, asks for confirmation, then calls
`ant.deploy.execute` with the user-approved list. Failure stops the chain at
the first non-zero return code.

---

## File-bus layout

All artifacts live under `${ANT_CONTEXT_ROOT}` (default `./.ant-context/`):

```
.ant-context/
├── personas/                                 # editable system prompts (on-disk wins)
│   ├── ana.md
│   ├── cham.md
│   ├── ark.md
│   ├── fey.md
│   ├── bud.md
│   ├── tess.md
│   └── shared_conventions.md
├── analysis/
│   └── NSS001-2026-06-03-r1.md               # Ana — overwritable within (date, r{N})
├── QA/
│   └── NSS001-2026-06-03-r1/
│       ├── round-1.md                        # Cham — append-only across rounds
│       ├── round-2.md
│       └── ...
├── architecture/
│   └── NSS001-2026-06-03-r1/
│       ├── roadmap/
│       │   └── roadmap.md                    # Ark
│       ├── frontend/
│       │   ├── NSS001Xhtml.md                # Fey, one md per artifact
│       │   ├── NSS001BackingBean.md
│       │   └── ...
│       ├── backend/
│       │   ├── NSS001Bl.md                   # Bud, one md per artifact
│       │   ├── NSS001BlImpl.md
│       │   └── ...
│       └── qa/
│           └── test-report.md                # Tess
└── .cache/
    ├── project-map.json                       # rebuilt on git HEAD/branch/dirty/pom change
    ├── jar-paths.json                         # GAV → resolved jar
    └── jars/{sha}/                            # per-jar deep-scan + optional decompile
```

### Revision rule (`-r{N}`)

Every (screenId, date) gets a fresh `-r{N}` suffix. The pipeline scans
`analysis/` for the highest existing `-r{N}` for the same screen+date and
allocates `N+1`. This propagates through all directories so a re-run never
clobbers prior QA rounds, architecture, or test reports.

### QA round rule

`QA/.../round-{N}.md` is **append-only**. Writing an explicit `round_n` that
already exists raises `FileExistsError`. The host loops Ana ⇄ Cham until either
two consecutive rounds report empty unresolved sections (convergence) or
`ANT_QA_MAX_ROUNDS` is hit (escalation).

---

## Editing personas

The seven persona prompts ship with the package. On first run, they are
**materialized** to `${ANT_CONTEXT_ROOT}/personas/`. From then on, the
**on-disk copy wins** — edit them per project to tighten conventions or add
domain rules.

To re-sync from the package, delete (or rename) the on-disk files and rerun any
slash command.

The MCP resource URIs `ant://persona/<name>` always reflect the on-disk copy
when present.

---

## Tools exposed

The server exposes these tools (callable directly by the host model in
addition to the slash-command prompts):

| Tool                       | Purpose                                                          |
| -------------------------- | ---------------------------------------------------------------- |
| `ant.workspace.preflight`  | Ingest Excels, allocate revision, run pipeline-specific gates.   |
| `ant.deploy.evaluate`      | Return the deploy directive (no side effects).                   |
| `ant.deploy.execute`       | Run an *already-approved* directive. Stops on first failure.     |
| `ant.codebase.scan`        | Refresh and return the project map.                              |
| `ant.dispatch.plan`        | Build the agent dispatch plan (groups, parallelism, paths).      |
| `ant.fs.write_artifact`    | Write an artifact under `.ant-context/` (idempotent).            |
| `ant.fs.read_artifact`     | Read an artifact by path.                                        |
| `ant.persona.load`         | Return persona text (on-disk wins, package fallback).            |

---

## Non-negotiables (encoded in `shared_conventions.md`)

These rules are part of every persona's binding preamble:

* **Total ingestion.** Read every sheet of every attached `.xlsx`. Never sample.
* **Strikethrough = invisible.** At cell *and* run level. Logged under "Excluded (struck-through)" but excluded from analysis text.
* **Required-field flagging.** Every required UI field is flagged in the analysis and roadmap.
* **`ASSUMPTION:` tag.** Any inferred koseiin-\* API or undocumented behaviour must be explicitly tagged. No fabricated method signatures.
* **Read koseiin-\* via resolved jars/sources.** Multi-repo means the dependency surface is reached through `~/.m2`, not sibling source trees.
* **Idempotent revisioned writes.** Within `(screen, date, r{N})`: analysis / roadmap / per-artifact md may be rewritten. QA rounds are append-only.
* **Mermaid for diagrams.** No ASCII art.
* **Never self-deploy.** The server emits a directive; the user runs it.
* **Output format.** H1 of the form `# {ScreenId} — {Doc} (r{N})` and source-cell citations like `(画面項目設計書 B14)`.

---

## Troubleshooting

Run the diagnostic:

```bat
ana-and-new-team doctor
```

It reports:

* package version, Python interpreter, platform,
* every `ANT_*` env var (set / unset / value),
* parsed `Settings` (or `ConfigError` reason if `ANT_KOSEIIN_REPOS` is malformed),
* persona inventory (bundled + materialized to `.ant-context/personas/`),
* PATH availability of `mvn`, `java`, `git`, `uvx`, `claude`, `code`,
* config-file paths for each supported AI host (and whether they exist).

For machine-readable output (e.g. to attach to a bug report):

```bat
ana-and-new-team doctor --json
```

To enumerate the live MCP surface (tools, prompts, resources) without
attaching a host:

```bat
ana-and-new-team inspect --json
```

---

## Development

```bat
git clone https://gitlab.enlinka.co/work-project/ana-and-new-team.git
cd ana-and-new-team
pip install -e .[dev]
pytest -q
```

The test suite includes:

* synthetic XLSX builders that exercise both run-level rich-text strikethrough and cell-level font strikethrough,
* `fs_state` revisioning + non-clobbering QA round semantics,
* `/ant-new-screen` HALT on missing プログラム設計書(簡易),
* deploy-gate directive shape and `ANT_KOSEIIN_REPOS` parsing (comma + JSON, malformed input),
* screenId extraction precedence (filename > workbook scan > none),
* project-map cache invalidation on git HEAD / branch / dirty / pom changes,
* `DispatchPlan` snapshot for `/ant-new-screen`,
* in-process MCP server smoke test (initialize → list tools / prompts / resources → call tool),
* CLI argparse routing + `doctor` / `inspect` / `install` subcommands,
* per-OS host config path resolution (`claude-code`, `opencode`, `cline`),
* idempotent JSON merge engine + `--dry-run` + `--force` semantics + `.bak` retention.

All fixtures are **synthetic** — no real customer documents are committed.

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the release flow and
[`CHANGELOG.md`](CHANGELOG.md) for version history.

---

## License

MIT — see `LICENSE`.
