Add v0.0.1 concept doc, README, ROADMAP, and implementation scaffold

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+* @DeepAgentLabs
+

.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+

.github/workflows/ci.yml

@@ -0,0 +1,60 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --extra dev --python ${{ matrix.python-version }}
+
+      - name: Lint (ruff check)
+        run: uv run ruff check src tests
+
+      # Scoped to src/tests, not ".". The repo docs intentionally contain
+      # pseudocode and architecture snippets that are not meant to be treated
+      # as executable Python by the formatter.
+      - name: Format check (ruff format)
+        run: uv run ruff format --check src tests
+
+      - name: Type check (mypy)
+        run: uv run mypy
+
+      - name: Test (pytest)
+        run: uv run pytest
+
+  package:
+    runs-on: ubuntu-latest
+    needs: [test]
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install dependencies
+        run: uv sync --extra dev --python 3.12
+      - name: Build distributions
+        run: |
+          uv run python -m build
+          uv run python -m twine check dist/*
+

.github/workflows/release-pypi.yml

@@ -0,0 +1,47 @@
+name: publish-pypi
+
+on:
+  release:
+    types: [published]
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish-pypi:
+    runs-on: ubuntu-latest
+    needs: build
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+

.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.venv/
+.DS_Store
+

AGENTS.md

@@ -0,0 +1,180 @@
+## agenticops-control-tower Development Reference
+
+## Ecosystem Context
+
+### Role in DeepAgentLabs
+
+`agenticops-control-tower` is the operations and control-plane layer in the
+DeepAgentLabs ecosystem. Its job is to centralize inventory, visibility,
+configuration, and operator workflows across many deployed agents and many
+DeepAgentLabs capabilities.
+
+### Owns
+
+- Agent registry, heartbeat, and fleet-inventory concerns
+- Capability discovery and version/status visibility across deployed agents
+- The unified control-plane API, CLI, and future console surface
+- Thin ecosystem adapters that summarize sibling-package posture without
+  re-implementing sibling-package logic
+
+### Does Not Own
+
+- The canonical operational schema or shared normative object model — that
+  belongs in `ai-operations-spec`
+- Core observability, profiling, evaluation, or recommendation logic — that
+  belongs in `agenticlens`
+- Fault injection and resilience-testing logic — that belongs in
+  `agentic-chaos`
+- Decision-time governance or pre-action intervention logic — that belongs in
+  `agentic-sidecar`
+- The MCP-native access surface itself — that belongs in
+  `deep-agentic-core-mcp`, even when it later connects to Control Tower
+
+### Integrates With
+
+- `ai-operations-spec` for shared terminology and any ecosystem-facing
+  inventory, status, or configuration contracts
+- `agenticlens` when Control Tower needs summarized observability or readiness
+  posture
+- `agentic-sidecar` when Control Tower needs summarized governance or risk
+  posture
+- `agentic-chaos` when Control Tower needs summarized experiment or resilience
+  posture
+- `deep-agentic-core-mcp` when the control plane is later exposed to AI
+  operators through MCP
+
+### Current Roadmap Focus
+
+The current build focus is the v0.1 registry and discovery core. Work in this
+repo should strengthen explicit registration, heartbeat handling, capability
+inventory, and the read-only control surface before attempting orchestration,
+bulk actions, or a rich dashboard.
+
+### Before You Build Here
+
+- Ask whether the feature is about operator control and fleet visibility; if it
+  is really analysis, governance, chaos execution, or MCP exposure, it may
+  belong in a sibling repo instead
+- Keep adapters thin and contract-driven; do not copy implementation logic from
+  Lens, Sidecar, Chaos, or MCP into this package
+- Build read-only inventory and status first; avoid jumping ahead to write-side
+  orchestration without the underlying control model in place
+
+## Status
+
+This repository is a **scaffold**. Package layout, docs, tests, and CI/release
+workflows exist; only a very small in-memory registry/discovery/API skeleton is
+implemented today. See [ROADMAP.md](ROADMAP.md) for the actual build order.
+
+## Build and Run
+
+- Install: `make install` (runs `uv sync --extra dev`)
+- Test: `make test` or `make check` (lint + format + typecheck + test)
+- Lint: `make lint`
+- Type check: `make typecheck`
+- CLI: not published yet — `[project.scripts]` is intentionally absent from
+  `pyproject.toml` until the CLI becomes a real supported surface
+
+## Code Style
+
+- Strict typing (mypy strict mode, Python 3.10+)
+- Line length: 100
+- Ruff rules: E, F, I, UP, B, SIM, N
+- One purpose per file (separation of concerns)
+- Control-plane artifacts should stay compatible with ecosystem-wide contract
+  work once those shapes are formalized
+
+## Design Constraints
+
+These are load-bearing, not preferences — see
+[ROADMAP.md](ROADMAP.md#design-constraints) for the full rationale:
+
+1. **Inventory before orchestration.** v0.1 should answer what exists and what
+   is installed before attempting remote change or fleet-wide mutation.
+2. **Read-only before write-capable.** Registration, discovery, and status must
+   be trustworthy before configuration or operations fan out across agents.
+3. **API and CLI before dashboard.** The console should sit on the same control
+   model, not become the hidden place where the real behavior lives.
+4. **Adapters stay thin.** `adapters/` should summarize or bridge, not own
+   Lens, Sidecar, Chaos, or MCP behavior.
+5. **Runtime agnostic means no early runtime lock-in.** Do not quietly design
+   the first release around one cloud, one orchestrator, or one framework.
+6. **MCP comes after the control API.** AI-native access is valuable, but it
+   should connect to a real control plane rather than a concept-only surface.
+
+## Repo Map
+
+| Path | Purpose | Planned version |
+|------|---------|------------------|
+| `src/agenticops_control_tower/models/` | Shared inventory and status models | v0.1 |
+| `src/agenticops_control_tower/registry/` | Agent registration, heartbeat, and inventory state | v0.1 |
+| `src/agenticops_control_tower/discovery/` | Capability discovery and normalization | v0.1 |
+| `src/agenticops_control_tower/api/` | Unified read-only control-plane API surface | v0.1 |
+| `src/agenticops_control_tower/cli/` | Operator CLI | v0.2 |
+| `src/agenticops_control_tower/console/` | AgenticOps Console / dashboard | v0.3 |
+| `src/agenticops_control_tower/config/` | Central configuration models and safe write paths | v0.4 |
+| `src/agenticops_control_tower/adapters/` | Thin ecosystem adapters to sibling projects and MCP | v0.5+ |
+| `examples/` | Sample registration and capability payloads | ongoing |
+| `tests/` | Pytest test suite | ongoing |
+| `Makefile` | Local dev automation | — |
+
+Full architecture and build order: [ROADMAP.md](ROADMAP.md).
+
+## Entry Points (planned)
+
+- Python API: read-only control surface through `api/`
+- CLI: `deepagent ...` (planned in v0.2)
+- Console: AgenticOps Console (planned in v0.3)
+
+## Package Boundaries
+
+- This package should stay **standalone** — `pip install
+  agenticops-control-tower` must work without requiring any other
+  DeepAgentLabs package
+- Sibling integrations must remain optional and degrade honestly when the
+  sibling package is unavailable
+- `api/` may depend on `registry/` and `discovery/`; the reverse should not be
+  true
+- `models/` must not import from adapters or UI layers
+- `console/` should consume the same underlying control model as `api/` and
+  `cli/`, not invent a parallel one
+
+## Adding a New Control-Plane Surface
+
+1. Confirm the feature belongs to operator control, inventory, configuration,
+   or fleet visibility rather than to a sibling runtime
+2. Add or update the shared model first if the feature changes inventory or
+   status meaning
+3. Add tests covering the read path before adding any write path
+4. Update `README.md` and `ROADMAP.md` if the feature changes milestone scope
+
+## Feature Completion Expectations
+
+- Every behavior change must include tests
+- User-facing features must include or update examples in `README.md`,
+  `examples/`, or docs
+- When a roadmap item or milestone meaningfully changes status, update
+  `README.md` and `ROADMAP.md` in the same change
+- If that milestone or release changes the public ecosystem story, also update
+  `/home/pramodbn27/PyPi Projects/.github/profile/README.md` and, when
+  relevant, `/home/pramodbn27/PyPi Projects/.github/profile/ROADMAP.md`
+- When work is packaged as a release-ready change, also update
+  `pyproject.toml`, `src/agenticops_control_tower/__init__.py`, and
+  `CHANGELOG.md`
+
+## Pre-push Checklist
+
+Run `make check` before every push. It runs: lint -> format-check -> typecheck
+-> test.
+
+## Release
+
+1. Bump version in `pyproject.toml`, `src/agenticops_control_tower/__init__.py`, and `CHANGELOG.md`
+2. Commit: `git commit -am "release: vX.Y.Z"`
+3. Tag: create an annotated `vX.Y.Z` tag and use the latest `CHANGELOG.md`
+   release section as the tag description
+4. Push: `git push origin main --tags`
+
+The `release-pypi.yml` workflow triggers on tag push or a published GitHub
+release and publishes to PyPI via Trusted Publishing once the `pypi` GitHub
+Environment and PyPI Trusted Publisher configuration exist.

CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.0.1
+
+- Initial repository scaffold
+- Concept-stage README and roadmap
+- Package layout, tests, and CI/release workflows
+

CI.md

@@ -0,0 +1,13 @@
+# CI
+
+The scaffold CI currently checks:
+
+- installability with `uv`
+- linting with `ruff`
+- formatting with `ruff format --check`
+- type checking with `mypy`
+- tests with `pytest`
+- package build integrity with `python -m build` and `twine check`
+
+The workflows live under [`.github/workflows/`](.github/workflows/).
+

CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing
+
+This repository is still in the scaffold stage.
+
+For now, contributions should stay focused on:
+
+- clarifying the control-plane boundary
+- tightening the registration and discovery model
+- building narrow, testable implementation slices from [ROADMAP.md](ROADMAP.md)
+
+Before opening a large feature PR, prefer aligning the milestone and package
+boundary first in an issue or design note.
+
+## Local development
+
+```bash
+make install
+make check
+```
+
+## Scope discipline
+
+`agenticops-control-tower` should own operator-facing control-plane behavior.
+If a change mostly adds observability logic, governance logic, chaos logic, or
+MCP logic, it may belong in a sibling repository instead.
+