Metadata-Version: 2.4
Name: ana-and-new-team
Version: 0.1.0a0
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.
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`).

## 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`.
