anrs 0.1.0__tar.gz

anrs-0.1.0/ANRS_README.md

@@ -0,0 +1,157 @@
+# ANRS: AI-Native Repo Spec
+
+> A practical specification for structuring AI-friendly code repositories.
+
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-0.1-blue.svg)]()
+[![Standard](https://img.shields.io/badge/AI%20Native-Repo%20Spec-green.svg)]()
+
+[English](README.md) | [中文](README.zh.md)
+
+---
+
+## What is ANRS?
+
+ANRS (AI-Native Repo Spec) is a vendor-neutral specification that defines how to structure a repository so that AI agents can work within it safely and effectively.
+
+When AI agents operate in traditional codebases, they often lose track of their current task, hallucinate commands, or modify unrelated files. ANRS solves this by providing a standard set of boundaries and context:
+
+- **Explicit State (`state.json`)** — Replaces fragile chat history. The AI always reads this file first to know "what task I am doing" and "what step I am on."
+- **Defined Skills (`skills/`)** — Replaces open-ended guessing. The AI is restricted to documented checklists, preventing undefined behaviors.
+- **Mandatory Harness (`.anrs/harness/`)** — Replaces blind commits. AI-generated code must pass checks and tests before task completion.
+
+> **Note**: ANRS is a **specification**, not a runtime tool. It's a standardized folder structure (`.anrs/`) plus execution protocols that any AI tool can follow.
+
+---
+
+## Design Principles
+
+- **Deterministic Execution** — AI follows a fixed loop: Read → Plan → Execute → Verify.
+- **Atomic Changes** — Code and state update together. Always rollback-safe.
+- **Vendor Neutral** — Works with Cursor, Claude, Codex, and others.
+- **Layered Verification** — Security → Lint → Test → Risk. Gate before commit.
+- **Learn from Failures** — Failed attempts are archived for future reference.
+
+---
+
+## Architecture Overview
+
+```
+                    ANRS Framework
+
+    State (SSOT)  →  Orchestrator  →  Skills
+         ↑              |              |
+         |              v              v
+         |           Harness  ←───  Code
+         |              |
+         |         [ PASS? ]
+         |          /     \
+         |        YES      NO
+         |         |        |
+         └── Commit       Reflection → Retry
+```
+
+---
+
+## Execution Workflow
+
+```
+1. READ STATE    → .anrs/state.json
+2. LOAD PLAN     → .anrs/plans/active/{task_id}.md
+3. SELECT SKILL  → .anrs/skills/index.json
+4. EXECUTE       → Follow SKILL.md checklist
+5. RUN HARNESS   → L1 (Static) → L2 (Tests) → L3 (Stability)
+
+PASS → Atomic commit → Update state → Done
+FAIL → Reflect → Retry (max 3) → Escalate to human
+```
+
+---
+
+## Quick Start
+
+### Option 1: Use CLI (Recommended)
+
+```bash
+pip install anrs
+cd your-project
+anrs init                    # Standard setup
+anrs adapter install cursor  # Add AI adapter
+```
+
+This creates:
+```
+your-project/
+├── .anrs/
+│   ├── ENTRY.md      # AI reads this first
+│   ├── state.json    # Current state (SSOT)
+│   ├── config.json   # Configuration
+│   ├── scratchpad.md # Temporary notes
+│   └── plans/        # Task plans
+│       ├── active/   # Current tasks
+│       ├── backlog/  # Future tasks
+│       └── templates/
+└── .cursorrules      # AI adapter
+```
+
+### Option 2: Explore the Source
+
+```bash
+git clone https://github.com/artsyne/anrs.git
+cd anrs
+ls -la spec/      # Protocol specification templates
+ls -la cli/       # CLI tool source code
+```
+
+### Option 3: Configure Your AI Platform
+
+ANRS provides ready-to-use adapters with **multi-mode support** (build/plan/review):
+
+| Platform | Modes | Quick Start |
+|----------|-------|--------------|
+| **Cursor** | build, plan | `anrs adapter install cursor` |
+| **Claude Code** | build, plan, review | `anrs adapter install claude-code` |
+| **Codex** | build, plan, review | `anrs adapter install codex` |
+| **OpenCode** | build, plan, review | `anrs adapter install opencode` |
+
+See [adapters documentation](cli/data/adapters/README.md) for manual setup and mode switching.
+
+---
+
+## Core Concepts
+
+**State (SSOT)** — `.anrs/state.json` — Single Source of Truth for task state. AI reads this before any action.
+
+**Entry Point** — `.anrs/ENTRY.md` — AI agent entry point. Defines rules, constraints, and available skills.
+
+**Skills** — `.anrs/skills/` — Registered action templates with input/output schemas and constraints.
+
+**Harness** — `.anrs/harness/quality_gate.py` (full level) or `anrs harness` command — Multi-layer evaluation gate (Security → L1: static → L2: tests → L3: stability).
+
+---
+
+## Key Files Reference
+
+| File | Description |
+|------|-------------|
+| `.anrs/ENTRY.md` | AI agent entry point |
+| `.anrs/state.json` | Current execution state |
+| `.anrs/config.json` | Project configuration |
+| `.anrs/plans/active/` | Active task plans |
+| `.anrs/harness/` | Quality gate evaluators (full level) |
+
+---
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) — 5-minute quick start
+- [Installation Guide](docs/installation.md) — Setup options (minimal/standard/full)
+- [Core Concepts](docs/concepts/overview.md) — Architecture and data flow
+- [Core Beliefs](spec/core-beliefs.md) — Design principles
+- [Contributing Guide](CONTRIBUTING.md) — How to contribute
+
+---
+
+## License
+
+MIT License — See [LICENSE](LICENSE) for details.

anrs-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include ANRS_README.md

anrs-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: anrs
+Version: 0.1.0
+Summary: ANRS (AI-Native Repo Spec) - A vendor-neutral specification for AI-friendly code repositories
+Author: ANRS Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/artsyne/anrs
+Project-URL: Documentation, https://artsyne.github.io/anrs
+Keywords: ai,specification,repository,automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-json-report>=1.5.0; extra == "dev"
+Provides-Extra: lint
+Requires-Dist: ruff>=0.1.0; extra == "lint"
+Requires-Dist: radon>=6.0.0; extra == "lint"
+Provides-Extra: security
+Requires-Dist: bandit>=1.7.0; extra == "security"
+Requires-Dist: pip-audit>=2.6.0; extra == "security"
+Provides-Extra: validate
+Requires-Dist: jsonschema>=4.0.0; extra == "validate"
+Requires-Dist: pyyaml>=6.0.0; extra == "validate"
+Provides-Extra: all
+Requires-Dist: anrs[dev,lint,security,validate]; extra == "all"
+
+# ANRS: AI-Native Repo Spec
+
+> A practical specification for structuring AI-friendly code repositories.
+
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-0.1-blue.svg)]()
+[![Standard](https://img.shields.io/badge/AI%20Native-Repo%20Spec-green.svg)]()
+
+[English](README.md) | [中文](README.zh.md)
+
+---
+
+## What is ANRS?
+
+ANRS (AI-Native Repo Spec) is a vendor-neutral specification that defines how to structure a repository so that AI agents can work within it safely and effectively.
+
+When AI agents operate in traditional codebases, they often lose track of their current task, hallucinate commands, or modify unrelated files. ANRS solves this by providing a standard set of boundaries and context:
+
+- **Explicit State (`state.json`)** — Replaces fragile chat history. The AI always reads this file first to know "what task I am doing" and "what step I am on."
+- **Defined Skills (`skills/`)** — Replaces open-ended guessing. The AI is restricted to documented checklists, preventing undefined behaviors.
+- **Mandatory Harness (`.anrs/harness/`)** — Replaces blind commits. AI-generated code must pass checks and tests before task completion.
+
+> **Note**: ANRS is a **specification**, not a runtime tool. It's a standardized folder structure (`.anrs/`) plus execution protocols that any AI tool can follow.
+
+---
+
+## Design Principles
+
+- **Deterministic Execution** — AI follows a fixed loop: Read → Plan → Execute → Verify.
+- **Atomic Changes** — Code and state update together. Always rollback-safe.
+- **Vendor Neutral** — Works with Cursor, Claude, Codex, and others.
+- **Layered Verification** — Security → Lint → Test → Risk. Gate before commit.
+- **Learn from Failures** — Failed attempts are archived for future reference.
+
+---
+
+## Architecture Overview
+
+```
+                    ANRS Framework
+
+    State (SSOT)  →  Orchestrator  →  Skills
+         ↑              |              |
+         |              v              v
+         |           Harness  ←───  Code
+         |              |
+         |         [ PASS? ]
+         |          /     \
+         |        YES      NO
+         |         |        |
+         └── Commit       Reflection → Retry
+```
+
+---
+
+## Execution Workflow
+
+```
+1. READ STATE    → .anrs/state.json
+2. LOAD PLAN     → .anrs/plans/active/{task_id}.md
+3. SELECT SKILL  → .anrs/skills/index.json
+4. EXECUTE       → Follow SKILL.md checklist
+5. RUN HARNESS   → L1 (Static) → L2 (Tests) → L3 (Stability)
+
+PASS → Atomic commit → Update state → Done
+FAIL → Reflect → Retry (max 3) → Escalate to human
+```
+
+---
+
+## Quick Start
+
+### Option 1: Use CLI (Recommended)
+
+```bash
+pip install anrs
+cd your-project
+anrs init                    # Standard setup
+anrs adapter install cursor  # Add AI adapter
+```
+
+This creates:
+```
+your-project/
+├── .anrs/
+│   ├── ENTRY.md      # AI reads this first
+│   ├── state.json    # Current state (SSOT)
+│   ├── config.json   # Configuration
+│   ├── scratchpad.md # Temporary notes
+│   └── plans/        # Task plans
+│       ├── active/   # Current tasks
+│       ├── backlog/  # Future tasks
+│       └── templates/
+└── .cursorrules      # AI adapter
+```
+
+### Option 2: Explore the Source
+
+```bash
+git clone https://github.com/artsyne/anrs.git
+cd anrs
+ls -la spec/      # Protocol specification templates
+ls -la cli/       # CLI tool source code
+```
+
+### Option 3: Configure Your AI Platform
+
+ANRS provides ready-to-use adapters with **multi-mode support** (build/plan/review):
+
+| Platform | Modes | Quick Start |
+|----------|-------|--------------|
+| **Cursor** | build, plan | `anrs adapter install cursor` |
+| **Claude Code** | build, plan, review | `anrs adapter install claude-code` |
+| **Codex** | build, plan, review | `anrs adapter install codex` |
+| **OpenCode** | build, plan, review | `anrs adapter install opencode` |
+
+See [adapters documentation](cli/data/adapters/README.md) for manual setup and mode switching.
+
+---
+
+## Core Concepts
+
+**State (SSOT)** — `.anrs/state.json` — Single Source of Truth for task state. AI reads this before any action.
+
+**Entry Point** — `.anrs/ENTRY.md` — AI agent entry point. Defines rules, constraints, and available skills.
+
+**Skills** — `.anrs/skills/` — Registered action templates with input/output schemas and constraints.
+
+**Harness** — `.anrs/harness/quality_gate.py` (full level) or `anrs harness` command — Multi-layer evaluation gate (Security → L1: static → L2: tests → L3: stability).
+
+---
+
+## Key Files Reference
+
+| File | Description |
+|------|-------------|
+| `.anrs/ENTRY.md` | AI agent entry point |
+| `.anrs/state.json` | Current execution state |
+| `.anrs/config.json` | Project configuration |
+| `.anrs/plans/active/` | Active task plans |
+| `.anrs/harness/` | Quality gate evaluators (full level) |
+
+---
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) — 5-minute quick start
+- [Installation Guide](docs/installation.md) — Setup options (minimal/standard/full)
+- [Core Concepts](docs/concepts/overview.md) — Architecture and data flow
+- [Core Beliefs](spec/core-beliefs.md) — Design principles
+- [Contributing Guide](CONTRIBUTING.md) — How to contribute
+
+---
+
+## License
+
+MIT License — See [LICENSE](LICENSE) for details.

anrs-0.1.0/README.md

@@ -0,0 +1,58 @@
+# ANRS CLI
+
+Command-line tool for managing ANRS-compliant repositories.
+
+## Installation
+
+```bash
+# From source
+cd cli
+pip install -e .
+
+# Or with dev dependencies
+pip install -e ".[dev]"
+```
+
+## Usage
+
+```bash
+# Initialize ANRS in a repository
+anrs init                    # Standard level
+anrs init --level minimal    # Minimal setup
+anrs init --level full       # Full setup
+
+# Check repository status
+anrs status
+
+# Run quality checks
+anrs harness                 # All levels
+anrs harness --level L1      # Static checks only
+anrs harness --strict        # Fail on any error
+
+# Manage adapters
+anrs adapter list
+anrs adapter install cursor
+anrs adapter install claude-code
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `anrs init` | Initialize ANRS in a repository |
+| `anrs status` | Show ANRS status and current state |
+| `anrs harness` | Run quality gate checks |
+| `anrs adapter` | Install and manage AI tool adapters |
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=anrs --cov-report=html
+```

anrs-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "anrs"
+version = "0.1.0"
+description = "ANRS (AI-Native Repo Spec) - A vendor-neutral specification for AI-friendly code repositories"
+readme = "ANRS_README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "ANRS Contributors"}
+]
+keywords = ["ai", "specification", "repository", "automation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "click>=8.0",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-cov>=4.0.0",
+    "pytest-json-report>=1.5.0",
+]
+lint = [
+    "ruff>=0.1.0",
+    "radon>=6.0.0",
+]
+security = [
+    "bandit>=1.7.0",
+    "pip-audit>=2.6.0",
+]
+validate = [
+    "jsonschema>=4.0.0",
+    "pyyaml>=6.0.0",
+]
+all = [
+    "anrs[dev,lint,security,validate]",
+]
+
+[project.scripts]
+anrs = "anrs.main:cli"
+
+[project.urls]
+Homepage = "https://github.com/artsyne/anrs"
+Documentation = "https://artsyne.github.io/anrs"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["anrs*"]
+
+[tool.setuptools.package-data]
+anrs = ["data/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = "-v --cov=anrs --cov-report=term-missing"

anrs-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

anrs-0.1.0/setup.py

@@ -0,0 +1,4 @@
+"""Setup script for editable installs."""
+from setuptools import setup
+
+setup()

anrs-0.1.0/src/anrs/__init__.py

@@ -0,0 +1,3 @@
+"""ANRS CLI - AI-Native Repo Spec command-line tool."""
+
+__version__ = "0.1.0"

anrs-0.1.0/src/anrs/adapter.py

@@ -0,0 +1,147 @@
+"""ANRS adapter command - Manage AI tool adapters."""
+
+import logging
+import shutil
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from anrs.constants import ADAPTERS_DIR, ADAPTERS, get_adapter_config_file
+from anrs.backup import (
+    ConflictStrategy,
+    backup_file,
+    get_backup_dir,
+    detect_user_modifications,
+    prompt_conflict_resolution,
+    show_conflict_summary,
+    create_backup_id,
+)
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+@click.group()
+def adapter():
+    """Manage AI tool adapters.
+
+    Install and configure adapters for different AI tools (Cursor, Claude Code, etc.)
+    """
+    pass
+
+
+@adapter.command("list")
+def list_adapters():
+    """List available adapters."""
+    table = Table(title="Available Adapters")
+    table.add_column("Adapter", style="cyan")
+    table.add_column("Description")
+    table.add_column("Config File")
+
+    for name, info in ADAPTERS.items():
+        table.add_row(name, info["description"], info["config_file"])
+
+    console.print(table)
+
+
+@adapter.command("install")
+@click.argument("adapter_name", type=click.Choice(list(ADAPTERS.keys())))
+@click.option(
+    "--force", "-f",
+    is_flag=True,
+    help="Overwrite existing adapter config (with automatic backup)"
+)
+@click.option(
+    "--skip",
+    is_flag=True,
+    help="Skip if adapter config already exists"
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    help="Show what would be done without making changes"
+)
+@click.argument("path", default=".", type=click.Path(exists=True))
+def install_adapter(adapter_name: str, force: bool, skip: bool, dry_run: bool, path: str):
+    """Install an adapter for an AI tool.
+
+    Creates a trampoline config file that points to .anrs/ENTRY.md.
+
+    \b
+    Conflict handling:
+    - Default: Asks how to handle existing files
+    - --force: Backup existing file, then overwrite
+    - --skip: Skip installation if file exists
+    """
+    target_dir = Path(path).resolve()
+    adapter_source = ADAPTERS_DIR / adapter_name
+
+    if not adapter_source.exists():
+        raise click.ClickException(f"Adapter not found: {adapter_name}")
+
+    config_file = get_adapter_config_file(adapter_name)
+    source_path = adapter_source / config_file
+    target_path = target_dir / config_file
+
+    # Detect conflict
+    conflict = None
+    if target_path.exists():
+        has_mods, diff = detect_user_modifications(source_path, target_path)
+        conflict = {
+            "file": config_file,
+            "status": "modified" if has_mods else "unchanged",
+            "diff": diff or "",
+        }
+
+    if dry_run:
+        console.print(
+            "[bold yellow]Dry run mode - no changes made[/bold yellow]")
+        console.print(f"Would copy: [cyan]{source_path}[/cyan]")
+        console.print(f"       to: [cyan]{target_path}[/cyan]")
+        if conflict:
+            console.print(
+                f"\n[yellow]Conflict:[/yellow] {config_file} already exists ({conflict['status']})")
+            console.print(
+                "[dim]Use --force to backup and overwrite, or --skip to skip[/dim]")
+        return
+
+    # Handle conflict
+    strategy = ConflictStrategy.BACKUP_AND_OVERWRITE
+    if conflict:
+        if skip:
+            console.print(f"[dim]Skipped: {config_file} already exists[/dim]")
+            return
+        elif force:
+            strategy = ConflictStrategy.BACKUP_AND_OVERWRITE
+        else:
+            show_conflict_summary(
+                [conflict], f"Adapter Config Conflict: {config_file}")
+            strategy = prompt_conflict_resolution()
+
+        if strategy == ConflictStrategy.ABORT:
+            raise click.Abort()
+        elif strategy == ConflictStrategy.SKIP:
+            console.print(f"[dim]Skipped: {config_file}[/dim]")
+            return
+
+    # Backup if overwriting
+    backup_id = create_backup_id()
+    if conflict and strategy == ConflictStrategy.BACKUP_AND_OVERWRITE:
+        anrs_dir = target_dir / ".anrs"
+        backup_dir = get_backup_dir(anrs_dir)
+        backup_path = backup_file(target_path, backup_dir, backup_id)
+        if backup_path:
+            console.print(f"[green]Backed up:[/green] {backup_path}")
+
+    try:
+        shutil.copy(source_path, target_path)
+    except IOError as e:
+        logger.error(f"Failed to install adapter: {e}")
+        raise click.ClickException(f"Cannot install adapter: {e}")
+
+    console.print(f"[green]Installed {adapter_name} adapter[/green]")
+    console.print(f"Config: [cyan]{target_path}[/cyan]")
+    console.print(
+        f"\nThe adapter will redirect AI to [cyan].anrs/ENTRY.md[/cyan]")