sia-package 0.2.0a0__tar.gz

sia_package-0.2.0a0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: sia-package
+Version: 0.2.0a0
+Summary: Self-Improving Agents (SIA) - A portable, host-agnostic instruction package that turns any coding assistant into a self-improving project collaborator.
+Home-page: https://github.com/GunjanGrunge/SIA_package
+Author: GunjanGrunge
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/GunjanGrunge/SIA_package
+Project-URL: Repository, https://github.com/GunjanGrunge/SIA_package
+Project-URL: Issues, https://github.com/GunjanGrunge/SIA_package/issues
+Keywords: sia,ai-agent,claude-code,antigravity,codex,bmad,superpowers,self-improving-agents,prompts,skills
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Dynamic: home-page
+Dynamic: requires-python
+
+
+# SIA (Self-Improving Agents)
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-0.2.0--alpha-00F2FE.svg?style=flat-square" alt="Version 0.2.0-alpha" />
+  <img src="https://img.shields.io/badge/status-active-success.svg?style=flat-square" alt="Status: Active" />
+  <img src="https://img.shields.io/badge/license-MIT-lightgrey.svg?style=flat-square" alt="License: MIT" />
+  <img src="https://img.shields.io/badge/host--agnostic-yes-7B2CBF.svg?style=flat-square" alt="Host-agnostic" />
+</p>
+
+> **A portable, host-agnostic instruction package that turns any coding assistant into a self-improving project collaborator.**
+
+It generates fresh, project-specific process artifacts: a project `AGENT.md`, a spec, an implementation plan, **modular feature-based project skills**, token savings metrics, and auditable subagent task records. You install SIA and state the goal; SIA derives the needed feature skills, delegates implementation through the host harness (Claude Code, Antigravity, Codex, etc.), reviews the results in your project root directory, and reports the integrated outcome with clear token savings metrics.
+
+This repo **is** the package. Clone it directly into a project as `sia/` and you're set up.
+
+## Architecture
+
+```text
+┌────────────────┐      ┌──────────────────────────┐      ┌─────────────────────────┐
+│  1. BOOTSTRAP  │ ---> │ 2. INTAKE & CLASSIFY     │ ---> │ 3. SPEC & AGENT.MD      │
+│  banner & mode │      │ Repo exploration/Goal    │      │ Specs & Standing Rules  │
+└────────────────┘      └──────────────────────────┘      └─────────────────────────┘
+                                                                       │
+┌────────────────┐      ┌──────────────────────────┐                   ▼
+│ 6. FEEDBACK    │ <--- │ 5. EXECUTION & AUDIT     │ <--- ┌─────────────────────────┐
+│ Loop & rules   │      │ Root Dir & Subagents     │      │ 4. MODULAR SKILL SYNTH  │
+└────────────────┘      └──────────────────────────┘      │ Feature Domain Skills   │
+                                                          └─────────────────────────┘
+```
+
+The full pipeline this package implements — see `AGENT.md` for the authoritative step-by-step version this diagram summarizes.
+
+## Install
+
+Initialize SIA in any project with your preferred package manager:
+
+```bash
+# Option A: npm / npx (Zero-install launcher)
+npx sia-agent init
+
+# Option B: Python / PyPI
+pip install sia-agent && sia init
+
+# Option C: Direct Git Clone
+git clone https://github.com/GunjanGrunge/SIA_package.git /path/to/your-project/sia
+```
+
+Then, in `your-project/`:
+
+1. **Read [`sia/INSTALL.md`](./INSTALL.md)** — gitignoring this vendored
+   folder correctly (while keeping the artifacts SIA *generates* for
+   your project committed), and an optional Claude Code discovery shim.
+2. **Tell your assistant once:** *"Read `sia/AGENT.md` and follow it."*
+   That's the one mandatory entry point — from there it runs Intake,
+   asks what it needs to, and generates your project's own `AGENT.md`,
+   spec, project skill(s), and plan using the guides under `sia/guides/`.
+   During execution it requires a brief, dispatch record, subagent report,
+   reviewer verdict, and integration report for each planned task.
+
+No API keys, no account, no cloud dependency. It's plain markdown
+instructions plus a small Python structure-test harness
+(`tests/validate_sia.py`) used only when developing this package itself.
+
+For the complete new-project, existing-project, Claude Code, Codex,
+subagent, reporting, and update workflow, read [USAGE.md](./USAGE.md).
+
+### Existing project? You choose the starting mode
+
+After the minimal safety check, SIA asks which way you want to begin:
+
+1. **Repository-informed exploration** — SIA reads a bounded set of
+   relevant artifacts, explains what it knows and does not know, then
+   asks what you want to build or change.
+2. **Goal-first** — SIA skips the broad repository scan and asks what you
+   want immediately, reading only what is needed for that request.
+3. **Conversational discovery** — you describe the project first; SIA
+   verifies only the evidence needed for the work that emerges.
+
+The chosen mode, evidence read, knowns, unknowns, and goal become part of
+the generated project record. SIA never claims it understands files it
+has not examined.
+
+### Attribution is automatic
+
+The public distribution adds a compact README badge and trailers to future
+SIA-mediated commits automatically—no slash command or toggle required.
+Trailers credit SIA's workflow while keeping the existing human Git author
+intact and linking the commit to project evidence. A direct user instruction
+to omit attribution is respected. See
+[`guides/attribution.md`](./guides/attribution.md) for the exact policy.
+
+## What's in here
+
+```
+AGENT.md                          # bootstrap — read this first
+guides/
+├── questioning-and-approval.md   # batching questions, severity-tagged approval gates
+├── writing-agent-md.md           # how to author a project's own AGENT.md
+├── writing-spec.md               # how to author a project spec
+├── writing-plan.md               # how to break a spec into a plan (file ownership, integration phase)
+├── writing-project-skills.md     # how SIA derives host-discoverable project skills
+├── subagent-task-brief.md        # task brief / report / progress-log / integration-report formats
+└── security-gate.md              # fixed threat-class checklist (software projects only)
+capture-interface.md              # feedback capture + the self-healing loop-engineering mechanism
+integrations/claude-code/SKILL.md # optional Claude Code auto-discovery shim
+INSTALL.md                        # how to add this to a project (gitignore policy, discovery)
+VALIDATION.md                     # the dogfood checklist this package is tested against
+USAGE.md                          # complete user guide for new and existing projects
+CHANGELOG.md
+tests/                            # structure-test harness (dev tooling, not needed to use SIA)
+```
+
+## Core idea
+
+SIA is a *generator*, not a library of pre-built templates. Every
+project gets its own fresh `AGENT.md`, spec, plan, and skill pack — never copied
+from another project — authored using the guides here. The one
+exception is `guides/security-gate.md`, a fixed, reused checklist for
+software projects.
+
+When a host supports subagents, SIA's controller is not allowed to
+silently replace a delegated implementation task with direct coding. A
+task is complete only with durable dispatch, implementation, review, and
+integration evidence; otherwise SIA reports the execution limitation to
+the user.
+
+The feedback loop (`capture-interface.md`) turns verified mistakes into
+project-specific standing rules with full provenance (source, evidence,
+severity, error class, scope, date, active/retired status), re-checked
+before every future proposal — so a project accumulates fewer repeated
+mistakes over its life instead of a longer history of the same ones.
+
+## Validation
+
+`VALIDATION.md` is the dogfood checklist this package is tested against
+before a version is called stable — real, previously-unseen codebases,
+not synthetic examples. A pilot validation report covering several real
+runs (including a full multi-subagent execution path: scoped task
+briefs, independent implementer subagents, an independent reviewer, and
+a real integration build) is maintained separately; ask the maintainer
+for a link if you want to see it.
+
+## License
+
+MIT.

sia_package-0.2.0a0/README.md

@@ -0,0 +1,145 @@
+
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-0.2.0--alpha-00F2FE.svg?style=flat-square" alt="Version 0.2.0-alpha" />
+  <img src="https://img.shields.io/badge/status-active-success.svg?style=flat-square" alt="Status: Active" />
+  <img src="https://img.shields.io/badge/license-MIT-lightgrey.svg?style=flat-square" alt="License: MIT" />
+  <img src="https://img.shields.io/badge/host--agnostic-yes-7B2CBF.svg?style=flat-square" alt="Host-agnostic" />
+</p>
+
+> **A portable, host-agnostic instruction package that turns any coding assistant into a self-improving project collaborator.**
+
+It generates fresh, project-specific process artifacts: a project `AGENT.md`, a spec, an implementation plan, **modular feature-based project skills**, token savings metrics, and auditable subagent task records. You install SIA and state the goal; SIA derives the needed feature skills, delegates implementation through the host harness (Claude Code, Antigravity, Codex, etc.), reviews the results in your project root directory, and reports the integrated outcome with clear token savings metrics.
+
+This repo **is** the package. Clone it directly into a project as `sia/` and you're set up.
+
+## Architecture
+
+```text
+┌────────────────┐      ┌──────────────────────────┐      ┌─────────────────────────┐
+│  1. BOOTSTRAP  │ ---> │ 2. INTAKE & CLASSIFY     │ ---> │ 3. SPEC & AGENT.MD      │
+│  banner & mode │      │ Repo exploration/Goal    │      │ Specs & Standing Rules  │
+└────────────────┘      └──────────────────────────┘      └─────────────────────────┘
+                                                                       │
+┌────────────────┐      ┌──────────────────────────┐                   ▼
+│ 6. FEEDBACK    │ <--- │ 5. EXECUTION & AUDIT     │ <--- ┌─────────────────────────┐
+│ Loop & rules   │      │ Root Dir & Subagents     │      │ 4. MODULAR SKILL SYNTH  │
+└────────────────┘      └──────────────────────────┘      │ Feature Domain Skills   │
+                                                          └─────────────────────────┘
+```
+
+The full pipeline this package implements — see `AGENT.md` for the authoritative step-by-step version this diagram summarizes.
+
+## Install
+
+Initialize SIA in any project with your preferred package manager:
+
+```bash
+# Option A: npm / npx (Zero-install launcher)
+npx sia-agent init
+
+# Option B: Python / PyPI
+pip install sia-agent && sia init
+
+# Option C: Direct Git Clone
+git clone https://github.com/GunjanGrunge/SIA_package.git /path/to/your-project/sia
+```
+
+Then, in `your-project/`:
+
+1. **Read [`sia/INSTALL.md`](./INSTALL.md)** — gitignoring this vendored
+   folder correctly (while keeping the artifacts SIA *generates* for
+   your project committed), and an optional Claude Code discovery shim.
+2. **Tell your assistant once:** *"Read `sia/AGENT.md` and follow it."*
+   That's the one mandatory entry point — from there it runs Intake,
+   asks what it needs to, and generates your project's own `AGENT.md`,
+   spec, project skill(s), and plan using the guides under `sia/guides/`.
+   During execution it requires a brief, dispatch record, subagent report,
+   reviewer verdict, and integration report for each planned task.
+
+No API keys, no account, no cloud dependency. It's plain markdown
+instructions plus a small Python structure-test harness
+(`tests/validate_sia.py`) used only when developing this package itself.
+
+For the complete new-project, existing-project, Claude Code, Codex,
+subagent, reporting, and update workflow, read [USAGE.md](./USAGE.md).
+
+### Existing project? You choose the starting mode
+
+After the minimal safety check, SIA asks which way you want to begin:
+
+1. **Repository-informed exploration** — SIA reads a bounded set of
+   relevant artifacts, explains what it knows and does not know, then
+   asks what you want to build or change.
+2. **Goal-first** — SIA skips the broad repository scan and asks what you
+   want immediately, reading only what is needed for that request.
+3. **Conversational discovery** — you describe the project first; SIA
+   verifies only the evidence needed for the work that emerges.
+
+The chosen mode, evidence read, knowns, unknowns, and goal become part of
+the generated project record. SIA never claims it understands files it
+has not examined.
+
+### Attribution is automatic
+
+The public distribution adds a compact README badge and trailers to future
+SIA-mediated commits automatically—no slash command or toggle required.
+Trailers credit SIA's workflow while keeping the existing human Git author
+intact and linking the commit to project evidence. A direct user instruction
+to omit attribution is respected. See
+[`guides/attribution.md`](./guides/attribution.md) for the exact policy.
+
+## What's in here
+
+```
+AGENT.md                          # bootstrap — read this first
+guides/
+├── questioning-and-approval.md   # batching questions, severity-tagged approval gates
+├── writing-agent-md.md           # how to author a project's own AGENT.md
+├── writing-spec.md               # how to author a project spec
+├── writing-plan.md               # how to break a spec into a plan (file ownership, integration phase)
+├── writing-project-skills.md     # how SIA derives host-discoverable project skills
+├── subagent-task-brief.md        # task brief / report / progress-log / integration-report formats
+└── security-gate.md              # fixed threat-class checklist (software projects only)
+capture-interface.md              # feedback capture + the self-healing loop-engineering mechanism
+integrations/claude-code/SKILL.md # optional Claude Code auto-discovery shim
+INSTALL.md                        # how to add this to a project (gitignore policy, discovery)
+VALIDATION.md                     # the dogfood checklist this package is tested against
+USAGE.md                          # complete user guide for new and existing projects
+CHANGELOG.md
+tests/                            # structure-test harness (dev tooling, not needed to use SIA)
+```
+
+## Core idea
+
+SIA is a *generator*, not a library of pre-built templates. Every
+project gets its own fresh `AGENT.md`, spec, plan, and skill pack — never copied
+from another project — authored using the guides here. The one
+exception is `guides/security-gate.md`, a fixed, reused checklist for
+software projects.
+
+When a host supports subagents, SIA's controller is not allowed to
+silently replace a delegated implementation task with direct coding. A
+task is complete only with durable dispatch, implementation, review, and
+integration evidence; otherwise SIA reports the execution limitation to
+the user.
+
+The feedback loop (`capture-interface.md`) turns verified mistakes into
+project-specific standing rules with full provenance (source, evidence,
+severity, error class, scope, date, active/retired status), re-checked
+before every future proposal — so a project accumulates fewer repeated
+mistakes over its life instead of a longer history of the same ones.
+
+## Validation
+
+`VALIDATION.md` is the dogfood checklist this package is tested against
+before a version is called stable — real, previously-unseen codebases,
+not synthetic examples. A pilot validation report covering several real
+runs (including a full multi-subagent execution path: scoped task
+briefs, independent implementer subagents, an independent reviewer, and
+a real integration build) is maintained separately; ask the maintainer
+for a link if you want to see it.
+
+## License
+
+MIT.

sia_package-0.2.0a0/banner.py

@@ -0,0 +1,218 @@
+"""
+SIA (Self-Improving Agents) - Terminal Startup & Status Banner
+===============================================================
+Compact, elegant startup banner in the style of modern developer CLIs (Claude Code).
+Features the official Hexagonal Prism 'S' vector mark in Electric Cyan,
+engine detection, working directory verification, and SIA project status audit.
+"""
+
+import os
+import sys
+import argparse
+from pathlib import Path
+
+# Electric Cyan Color Palette
+CYAN = "\033[38;2;0;242;254m"
+BOLD_CYAN = "\033[1m\033[38;2;0;242;254m"
+DIM = "\033[38;2;120;135;155m"
+GREEN = "\033[38;2;0;229;163m"
+YELLOW = "\033[38;2;255;191;0m"
+RED = "\033[38;2;255;75;75m"
+RESET = "\033[0m"
+
+VERSION = "0.2.0-alpha"
+
+def is_color_enabled() -> bool:
+    return not bool(os.environ.get("NO_COLOR")) and sys.stdout.isatty()
+
+def detect_host_engine() -> str:
+    """Detect active coding assistant host environment/engine"""
+    if os.environ.get("CLAUDE_CODE") or os.environ.get("CLAUDE_CODE_ENTRY"):
+        return "Claude Code (Terminal)"
+    elif os.environ.get("ANTIGRAVITY_IDE") or "antigravity" in sys.executable.lower():
+        return "Antigravity IDE"
+    elif os.environ.get("CODEX_CLI") or os.environ.get("CODEX_SESSION"):
+        return "Codex CLI"
+    elif "cursor" in os.environ.get("PATH", "").lower():
+        return "Cursor / Host Agent"
+    else:
+        return "Generic Host Engine (Claude/Codex/Antigravity)"
+
+def verify_working_directory() -> tuple[str, bool]:
+    """Verify if execution directory is inside target project root or hidden workingtree"""
+    cwd = os.getcwd()
+    is_workingtree = ".claude/workingtree" in cwd.replace("\\", "/") or "scratch/" in cwd.replace("\\", "/")
+    return cwd, not is_workingtree
+
+# Official High-Definition Hexagonal Prism 'S' Vector Mark
+HEX_PRISM_MARK = [
+    "         ⣠⣴⣶⣄       ",
+    "      ⢀⣴⣾⣿⣿⣿⣿⣿⣦⣄    ",
+    "    ⣠⣾⣿⣿⡿⠋⠁ ⠙⠿⣿⣿⣷⣦⡀  ",
+    "  ⣴⣿⣿⣿⠟⠉ ⢀⣠⣄  ⠈⠛⣿⣿⣿⡗ ",
+    "  ⣿⣿⣯⡀  ⠐⢿⣿⣿⣷⣤⡀⠐⢿⣿⡟ ",
+    "  ⠙⢿⣿⣿⣷⣄  ⠈⠻⣿⣿⣿⣦⣀⠉   ",
+    "    ⠙⠻⣿⣿⣷⣦⡀  ⠙⢿⣿⣿⣷⣄⡀ ",
+    "   ⢠⣷⣄⠈⠻⢿⣿⣿⣶⣄  ⠉⠻⣿⣿⣿ ",
+    "  ⢠⣿⣿⣿⠃  ⠙⠿⡿⠟⠁ ⢀⣤⣾⣿⣿ ",
+    "  ⠘⠻⣿⣿⣿⣦⣄    ⣠⣶⣿⣿⡿⠛⠁ ",
+    "     ⠙⠿⣿⣿⣷⣦⣴⣾⣿⣿⠟⠋     ",
+    "       ⠈⠛⢿⣿⣿⡿⠋⠁      "
+]
+
+def get_claude_code_banner(version=VERSION, cwd=None) -> str:
+    """Centered compact splash screen in vibrant Electric Cyan (Claude Code style)"""
+    if cwd is None:
+        cwd, is_valid_root = verify_working_directory()
+        home = os.path.expanduser("~")
+        if cwd.startswith(home):
+            cwd = "~" + cwd[len(home):]
+
+    engine = detect_host_engine()
+    c = BOLD_CYAN if is_color_enabled() else ""
+    cyan_reg = CYAN if is_color_enabled() else ""
+    d = DIM if is_color_enabled() else ""
+    g = GREEN if is_color_enabled() else ""
+    r = RESET if is_color_enabled() else ""
+
+    lines = [""]
+    for row in HEX_PRISM_MARK:
+        lines.append(f"        {c}{row}{r}")
+
+    lines.append("")
+    lines.append(f"              {c}SIA{r} {d}v{version}{r}")
+    lines.append(f"         {cyan_reg}Self-Improving Agents{r}")
+    lines.append("")
+    lines.append(f"      {c}•{r} Engine           : {g}{engine}{r}")
+    lines.append(f"      {c}•{r} Loop Engineering : {g}active{r}")
+    lines.append(f"      {c}•{r} Security Gate    : {g}armed{r}")
+    lines.append(f"      {c}•{r} Human Gates      : {d}questioning & approval{r}")
+    lines.append(f"      {c}•{r} Directory        : {d}{cwd}{r}")
+    lines.append("")
+    return "\n".join(lines)
+
+def get_inline_banner(version=VERSION, cwd=None) -> str:
+    """Inline side-by-side compact banner in Electric Cyan"""
+    if cwd is None:
+        cwd, is_valid_root = verify_working_directory()
+        home = os.path.expanduser("~")
+        if cwd.startswith(home):
+            cwd = "~" + cwd[len(home):]
+
+    engine = detect_host_engine()
+    c = BOLD_CYAN if is_color_enabled() else ""
+    cyan_reg = CYAN if is_color_enabled() else ""
+    d = DIM if is_color_enabled() else ""
+    g = GREEN if is_color_enabled() else ""
+    r = RESET if is_color_enabled() else ""
+
+    side_text = [
+        "",
+        "",
+        f"    {c}SIA{r} {d}v{version}{r}",
+        f"    {cyan_reg}Self-Improving Agents{r}",
+        "",
+        f"    {c}•{r} engine: {g}{engine}{r}",
+        f"    {c}•{r} loop: {g}active{r}  {d}•{r}  security: {g}armed{r}",
+        f"    {c}•{r} cwd: {d}{cwd}{r}",
+        "",
+        "",
+        "",
+        ""
+    ]
+
+    lines = [""]
+    for i in range(len(HEX_PRISM_MARK)):
+        l = f"{c}{HEX_PRISM_MARK[i]}{r}"
+        s = side_text[i]
+        lines.append(f"  {l}{s}")
+    lines.append("")
+    return "\n".join(lines)
+
+def print_status_audit():
+    """Print comprehensive SIA project status, modular skills, and token savings"""
+    c = BOLD_CYAN if is_color_enabled() else ""
+    d = DIM if is_color_enabled() else ""
+    g = GREEN if is_color_enabled() else ""
+    y = YELLOW if is_color_enabled() else ""
+    r = RESET if is_color_enabled() else ""
+
+    cwd, is_root_valid = verify_working_directory()
+    engine = detect_host_engine()
+
+    print(f"\n{c}=== SIA Status & Project Audit ==={r}")
+    print(f"SIA Version   : {g}{VERSION}{r}")
+    print(f"Host Engine   : {g}{engine}{r}")
+    print(f"Working Dir   : {d}{cwd}{r} {'[' + g + 'OK: Project Root' + r + ']' if is_root_valid else '[' + y + 'WARN: Isolated Sandbox' + r + ']'}")
+
+    # Check for project AGENT.md
+    agent_file = Path("AGENT.md")
+    if agent_file.exists():
+        print(f"Project AGENT : {g}Present ({agent_file.stat().st_size} bytes){r}")
+    else:
+        print(f"Project AGENT : {y}Not generated yet (Run SIA Intake){r}")
+
+    # Inspect skills directory
+    skills_dir = Path("skills")
+    modular_skills = list(skills_dir.glob("*/SKILL.md")) if skills_dir.exists() else []
+    print(f"Modular Skills: {g}{len(modular_skills)} active feature skill(s){r}")
+    for s in modular_skills:
+        print(f"  - {d}{s}{r}")
+
+    # Inspect SDD records
+    sdd_dir = Path("sdd")
+    if sdd_dir.exists():
+        progress_file = sdd_dir / "progress.md"
+        manifest_file = sdd_dir / "skill-manifest.md"
+        print(f"Execution Gate: {g}SDD records active{r}")
+        if progress_file.exists():
+            print(f"Progress Log   : {d}{progress_file}{r}")
+        if manifest_file.exists():
+            print(f"Skill Manifest : {d}{manifest_file}{r}")
+    else:
+        print(f"Execution Gate: {d}No active plan execution in sdd/{r}")
+
+    print(f"Token Accounting: {g}Active (Tracking Tokens Used & Baseline Context Savings){r}")
+    print(f"{c}===================================={r}\n")
+
+def print_banner(inline=False, version=VERSION):
+    """Main API function to print the banner to stdout"""
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+
+    if inline:
+        print(get_inline_banner(version=version))
+    else:
+        print(get_claude_code_banner(version=version))
+
+def main():
+    parser = argparse.ArgumentParser(description="SIA Terminal Startup Banner & Status Audit")
+    parser.add_argument("--inline", action="store_true", help="Display inline side-by-side instead of centered stacked")
+    parser.add_argument("--status", "--check", action="store_true", help="Print current SIA project status, modular skills & token savings")
+    parser.add_argument("--save-txt", type=str, default=None, help="Save plain-text banner to file")
+    args = parser.parse_args()
+
+    if args.status:
+        print_status_audit()
+        return
+
+    if args.save_txt:
+        os.environ["NO_COLOR"] = "1"
+        content = get_inline_banner() if args.inline else get_claude_code_banner()
+        content_clean = content.strip("\r\n") + "\n"
+        # Replace actual directory with <current project directory> placeholder for release distribution
+        cwd, _ = verify_working_directory()
+        home = os.path.expanduser("~")
+        if cwd.startswith(home):
+            cwd = "~" + cwd[len(home):]
+        content_clean = content_clean.replace(cwd, "<current project directory>")
+        with open(args.save_txt, "w", encoding="utf-8") as f:
+            f.write(content_clean)
+        print(f"Saved banner to {args.save_txt}")
+    else:
+        print_banner(inline=args.inline)
+
+if __name__ == "__main__":
+    main()

sia_package-0.2.0a0/cli.py

@@ -0,0 +1,104 @@
+"""
+SIA (Self-Improving Agents) - Unified Python CLI & Plugin Launcher
+====================================================================
+Provides `sia init`, `sia status`, `pip install sia-agent`, and `pipx` CLI tooling.
+"""
+
+import os
+import sys
+import shutil
+import argparse
+from pathlib import Path
+from banner import print_status_audit, print_banner, VERSION
+
+PACKAGE_ROOT = Path(__file__).resolve().parent
+
+def print_help():
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+    print(f"""
+\033[1m\033[38;2;0;242;254mSIA (Self-Improving Agents) Python CLI v{VERSION}\033[0m
+
+\033[36mUsage:\033[0m
+  sia init       Initialize SIA in current project (vendors sia/ & sets up discovery shims)
+  sia status     Run SIA project audit, check active skills & token savings
+  sia banner     Display terminal launch banner
+  sia --help     Show this help guide
+
+\033[36mQuickstart:\033[0m
+  1. Run \033[32msia init\033[0m inside your target project directory.
+  2. Tell your assistant: \033[33m"Read sia/AGENT.md and follow it."\033[0m
+  3. Verify status anytime with \033[32msia status\033[0m.
+""")
+
+def init_sia():
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+    cwd = Path.cwd().resolve()
+    sia_target = cwd / "sia"
+
+    print(f"\033[36m[SIA]\033[0m Initializing SIA v{VERSION} in project root: \033[33m{cwd}\033[0m")
+
+    if cwd != PACKAGE_ROOT.resolve():
+        sia_target.mkdir(parents=True, exist_ok=True)
+        items_to_copy = ['AGENT.md', 'BANNER.txt', 'CHANGELOG.md', 'INSTALL.md', 'README.md', 'USAGE.md', 'VALIDATION.md', 'banner.py', 'capture-interface.md', 'guides', 'integrations']
+        for item in items_to_copy:
+            src = PACKAGE_ROOT / item
+            dest = sia_target / item
+            if src.exists():
+                if src.is_dir():
+                    shutil.copytree(src, dest, dirs_exist_ok=True)
+                else:
+                    shutil.copy2(src, dest)
+        print("\033[32m✔ Vendored SIA files copied to ./sia/\033[0m")
+    else:
+        print("\033[32m✔ Currently in SIA package repository root.\033[0m")
+
+    # Update .gitignore
+    gitignore_path = cwd / ".gitignore"
+    gitignore_content = gitignore_path.read_text(encoding="utf-8") if gitignore_path.exists() else ""
+    if "sia/" not in gitignore_content:
+        with open(gitignore_path, "a", encoding="utf-8") as f:
+            f.write("\n# Vendored SIA (Self Improving Agents) tooling\nsia/\n")
+        print("\033[32m✔ Added sia/ to .gitignore\033[0m")
+    else:
+        print("\033[32m✔ .gitignore already configured for sia/\033[0m")
+
+    # Set up Claude Code discovery shim
+    claude_skills_dir = cwd / ".claude" / "skills" / "sia"
+    claude_skills_dir.mkdir(parents=True, exist_ok=True)
+    shim_src = PACKAGE_ROOT / "integrations" / "claude-code" / "SKILL.md"
+    shim_dest = claude_skills_dir / "SKILL.md"
+    if shim_src.exists():
+        shutil.copy2(shim_src, shim_dest)
+        print("\033[32m✔ Installed Claude Code discovery shim at .claude/skills/sia/SKILL.md\033[0m")
+
+    print("\n\033[1m\033[32mSIA successfully initialized!\033[0m")
+    print("Tell your assistant: \033[1m\033[33m\"Read sia/AGENT.md and follow it.\"\033[0m\n")
+
+def main():
+    parser = argparse.ArgumentParser(description="SIA Python CLI & Plugin Launcher", add_help=False)
+    parser.add_argument("command", nargs="?", default="help", help="Command: init, status, banner, help")
+    parser.add_argument("--help", "-h", action="store_true", help="Show help message")
+    parser.add_argument("--status", "--check", action="store_true", help="Run status audit")
+    args, unknown = parser.parse_known_args()
+
+    cmd = args.command.lower() if args.command else "help"
+
+    if args.help or cmd in ["help", "--help", "-h"]:
+        print_help()
+    elif args.status or cmd in ["status", "check", "--status", "--check"]:
+        print_status_audit()
+    elif cmd == "init":
+        init_sia()
+    elif cmd == "banner":
+        print_banner()
+    else:
+        print_help()
+
+if __name__ == "__main__":
+    main()

sia_package-0.2.0a0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sia-package"
+version = "0.2.0-alpha"
+description = "Self-Improving Agents (SIA) - A portable, host-agnostic instruction package that turns any coding assistant into a self-improving project collaborator."
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "GunjanGrunge" }
+]
+keywords = [
+    "sia",
+    "ai-agent",
+    "claude-code",
+    "antigravity",
+    "codex",
+    "bmad",
+    "superpowers",
+    "self-improving-agents",
+    "prompts",
+    "skills"
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules"
+]
+requires-python = ">=3.9"
+
+[project.urls]
+Homepage = "https://github.com/GunjanGrunge/SIA_package"
+Repository = "https://github.com/GunjanGrunge/SIA_package"
+Issues = "https://github.com/GunjanGrunge/SIA_package/issues"
+
+[project.scripts]
+sia = "cli:main"
+sia-agent = "cli:main"

sia_package-0.2.0a0/setup.cfg

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

sia_package-0.2.0a0/setup.py

@@ -0,0 +1,27 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="sia-package",
+    version="0.2.0-alpha",
+    description="Self-Improving Agents (SIA) - A portable, host-agnostic instruction package that turns any coding assistant into a self-improving project collaborator.",
+    long_description=open("README.md", encoding="utf-8").read(),
+    long_description_content_type="text/markdown",
+    author="GunjanGrunge",
+    url="https://github.com/GunjanGrunge/SIA_package",
+    license="MIT",
+    py_modules=["cli", "banner"],
+    packages=find_packages(),
+    include_package_data=True,
+    entry_points={
+        "console_scripts": [
+            "sia=cli:main",
+            "sia-agent=cli:main",
+        ],
+    },
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "Programming Language :: Python :: 3",
+    ],
+    python_requires=">=3.9",
+)

sia_package-0.2.0a0/sia_package.egg-info/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: sia-package
+Version: 0.2.0a0
+Summary: Self-Improving Agents (SIA) - A portable, host-agnostic instruction package that turns any coding assistant into a self-improving project collaborator.
+Home-page: https://github.com/GunjanGrunge/SIA_package
+Author: GunjanGrunge
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/GunjanGrunge/SIA_package
+Project-URL: Repository, https://github.com/GunjanGrunge/SIA_package
+Project-URL: Issues, https://github.com/GunjanGrunge/SIA_package/issues
+Keywords: sia,ai-agent,claude-code,antigravity,codex,bmad,superpowers,self-improving-agents,prompts,skills
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Dynamic: home-page
+Dynamic: requires-python
+
+
+# SIA (Self-Improving Agents)
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-0.2.0--alpha-00F2FE.svg?style=flat-square" alt="Version 0.2.0-alpha" />
+  <img src="https://img.shields.io/badge/status-active-success.svg?style=flat-square" alt="Status: Active" />
+  <img src="https://img.shields.io/badge/license-MIT-lightgrey.svg?style=flat-square" alt="License: MIT" />
+  <img src="https://img.shields.io/badge/host--agnostic-yes-7B2CBF.svg?style=flat-square" alt="Host-agnostic" />
+</p>
+
+> **A portable, host-agnostic instruction package that turns any coding assistant into a self-improving project collaborator.**
+
+It generates fresh, project-specific process artifacts: a project `AGENT.md`, a spec, an implementation plan, **modular feature-based project skills**, token savings metrics, and auditable subagent task records. You install SIA and state the goal; SIA derives the needed feature skills, delegates implementation through the host harness (Claude Code, Antigravity, Codex, etc.), reviews the results in your project root directory, and reports the integrated outcome with clear token savings metrics.
+
+This repo **is** the package. Clone it directly into a project as `sia/` and you're set up.
+
+## Architecture
+
+```text
+┌────────────────┐      ┌──────────────────────────┐      ┌─────────────────────────┐
+│  1. BOOTSTRAP  │ ---> │ 2. INTAKE & CLASSIFY     │ ---> │ 3. SPEC & AGENT.MD      │
+│  banner & mode │      │ Repo exploration/Goal    │      │ Specs & Standing Rules  │
+└────────────────┘      └──────────────────────────┘      └─────────────────────────┘
+                                                                       │
+┌────────────────┐      ┌──────────────────────────┐                   ▼
+│ 6. FEEDBACK    │ <--- │ 5. EXECUTION & AUDIT     │ <--- ┌─────────────────────────┐
+│ Loop & rules   │      │ Root Dir & Subagents     │      │ 4. MODULAR SKILL SYNTH  │
+└────────────────┘      └──────────────────────────┘      │ Feature Domain Skills   │
+                                                          └─────────────────────────┘
+```
+
+The full pipeline this package implements — see `AGENT.md` for the authoritative step-by-step version this diagram summarizes.
+
+## Install
+
+Initialize SIA in any project with your preferred package manager:
+
+```bash
+# Option A: npm / npx (Zero-install launcher)
+npx sia-agent init
+
+# Option B: Python / PyPI
+pip install sia-agent && sia init
+
+# Option C: Direct Git Clone
+git clone https://github.com/GunjanGrunge/SIA_package.git /path/to/your-project/sia
+```
+
+Then, in `your-project/`:
+
+1. **Read [`sia/INSTALL.md`](./INSTALL.md)** — gitignoring this vendored
+   folder correctly (while keeping the artifacts SIA *generates* for
+   your project committed), and an optional Claude Code discovery shim.
+2. **Tell your assistant once:** *"Read `sia/AGENT.md` and follow it."*
+   That's the one mandatory entry point — from there it runs Intake,
+   asks what it needs to, and generates your project's own `AGENT.md`,
+   spec, project skill(s), and plan using the guides under `sia/guides/`.
+   During execution it requires a brief, dispatch record, subagent report,
+   reviewer verdict, and integration report for each planned task.
+
+No API keys, no account, no cloud dependency. It's plain markdown
+instructions plus a small Python structure-test harness
+(`tests/validate_sia.py`) used only when developing this package itself.
+
+For the complete new-project, existing-project, Claude Code, Codex,
+subagent, reporting, and update workflow, read [USAGE.md](./USAGE.md).
+
+### Existing project? You choose the starting mode
+
+After the minimal safety check, SIA asks which way you want to begin:
+
+1. **Repository-informed exploration** — SIA reads a bounded set of
+   relevant artifacts, explains what it knows and does not know, then
+   asks what you want to build or change.
+2. **Goal-first** — SIA skips the broad repository scan and asks what you
+   want immediately, reading only what is needed for that request.
+3. **Conversational discovery** — you describe the project first; SIA
+   verifies only the evidence needed for the work that emerges.
+
+The chosen mode, evidence read, knowns, unknowns, and goal become part of
+the generated project record. SIA never claims it understands files it
+has not examined.
+
+### Attribution is automatic
+
+The public distribution adds a compact README badge and trailers to future
+SIA-mediated commits automatically—no slash command or toggle required.
+Trailers credit SIA's workflow while keeping the existing human Git author
+intact and linking the commit to project evidence. A direct user instruction
+to omit attribution is respected. See
+[`guides/attribution.md`](./guides/attribution.md) for the exact policy.
+
+## What's in here
+
+```
+AGENT.md                          # bootstrap — read this first
+guides/
+├── questioning-and-approval.md   # batching questions, severity-tagged approval gates
+├── writing-agent-md.md           # how to author a project's own AGENT.md
+├── writing-spec.md               # how to author a project spec
+├── writing-plan.md               # how to break a spec into a plan (file ownership, integration phase)
+├── writing-project-skills.md     # how SIA derives host-discoverable project skills
+├── subagent-task-brief.md        # task brief / report / progress-log / integration-report formats
+└── security-gate.md              # fixed threat-class checklist (software projects only)
+capture-interface.md              # feedback capture + the self-healing loop-engineering mechanism
+integrations/claude-code/SKILL.md # optional Claude Code auto-discovery shim
+INSTALL.md                        # how to add this to a project (gitignore policy, discovery)
+VALIDATION.md                     # the dogfood checklist this package is tested against
+USAGE.md                          # complete user guide for new and existing projects
+CHANGELOG.md
+tests/                            # structure-test harness (dev tooling, not needed to use SIA)
+```
+
+## Core idea
+
+SIA is a *generator*, not a library of pre-built templates. Every
+project gets its own fresh `AGENT.md`, spec, plan, and skill pack — never copied
+from another project — authored using the guides here. The one
+exception is `guides/security-gate.md`, a fixed, reused checklist for
+software projects.
+
+When a host supports subagents, SIA's controller is not allowed to
+silently replace a delegated implementation task with direct coding. A
+task is complete only with durable dispatch, implementation, review, and
+integration evidence; otherwise SIA reports the execution limitation to
+the user.
+
+The feedback loop (`capture-interface.md`) turns verified mistakes into
+project-specific standing rules with full provenance (source, evidence,
+severity, error class, scope, date, active/retired status), re-checked
+before every future proposal — so a project accumulates fewer repeated
+mistakes over its life instead of a longer history of the same ones.
+
+## Validation
+
+`VALIDATION.md` is the dogfood checklist this package is tested against
+before a version is called stable — real, previously-unseen codebases,
+not synthetic examples. A pilot validation report covering several real
+runs (including a full multi-subagent execution path: scoped task
+briefs, independent implementer subagents, an independent reviewer, and
+a real integration build) is maintained separately; ask the maintainer
+for a link if you want to see it.
+
+## License
+
+MIT.

sia_package-0.2.0a0/sia_package.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+banner.py
+cli.py
+pyproject.toml
+setup.py
+sia_package.egg-info/PKG-INFO
+sia_package.egg-info/SOURCES.txt
+sia_package.egg-info/dependency_links.txt
+sia_package.egg-info/entry_points.txt
+sia_package.egg-info/top_level.txt
+tests/test_validate_sia_self.py

sia_package-0.2.0a0/sia_package.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sia_package-0.2.0a0/sia_package.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+sia = cli:main
+sia-agent = cli:main

sia_package-0.2.0a0/sia_package.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+banner
+cli

sia_package-0.2.0a0/tests/test_validate_sia_self.py

@@ -0,0 +1,32 @@
+import subprocess
+import sys
+import tempfile
+import textwrap
+from pathlib import Path
+
+import validate_sia  # noqa: E402  (sia/tests is on sys.path when run from that dir)
+
+
+def test_assert_contains_raises_on_missing_pattern(tmp_path, monkeypatch):
+    monkeypatch.setattr(validate_sia, "SIA_ROOT", tmp_path)
+    (tmp_path / "sample.md").write_text("# Title\nbody text\n", encoding="utf-8")
+    try:
+        validate_sia.assert_contains("sample.md", [r"^# Title$", r"not present here"])
+        assert False, "expected AssertionError"
+    except AssertionError as exc:
+        assert "not present here" in str(exc)
+
+
+def test_assert_contains_passes_when_all_patterns_found(tmp_path, monkeypatch):
+    monkeypatch.setattr(validate_sia, "SIA_ROOT", tmp_path)
+    (tmp_path / "sample.md").write_text("# Title\nbody text\n", encoding="utf-8")
+    validate_sia.assert_contains("sample.md", [r"^# Title$", r"body text"])
+
+
+def test_assert_contains_raises_on_missing_file(tmp_path, monkeypatch):
+    monkeypatch.setattr(validate_sia, "SIA_ROOT", tmp_path)
+    try:
+        validate_sia.assert_contains("missing.md", [r"anything"])
+        assert False, "expected AssertionError"
+    except AssertionError as exc:
+        assert "does not exist" in str(exc)