aedile 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. aedile-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md +31 -0
  2. aedile-1.0.0/.github/ISSUE_TEMPLATE/feature_request.md +20 -0
  3. aedile-1.0.0/.github/pull_request_template.md +17 -0
  4. aedile-1.0.0/.github/workflows/ci.yml +69 -0
  5. aedile-1.0.0/.gitignore +121 -0
  6. aedile-1.0.0/CODE_OF_CONDUCT.md +37 -0
  7. aedile-1.0.0/CONTRIBUTING.md +44 -0
  8. aedile-1.0.0/LICENSE +21 -0
  9. aedile-1.0.0/PKG-INFO +134 -0
  10. aedile-1.0.0/README.md +115 -0
  11. aedile-1.0.0/SECURITY.md +18 -0
  12. aedile-1.0.0/SUPPORTED_AGENTS.md +62 -0
  13. aedile-1.0.0/aedile.toml +63 -0
  14. aedile-1.0.0/benchmarks/BENCHMARKS.md +24 -0
  15. aedile-1.0.0/benchmarks/results.json +92 -0
  16. aedile-1.0.0/benchmarks/run_benchmarks.py +152 -0
  17. aedile-1.0.0/docs/ARCHITECTURE.md +70 -0
  18. aedile-1.0.0/docs/COMPETITORS.md +53 -0
  19. aedile-1.0.0/docs/DECISION_LADDER.md +35 -0
  20. aedile-1.0.0/docs/DESIGN.md +56 -0
  21. aedile-1.0.0/docs/FAQ.md +23 -0
  22. aedile-1.0.0/images/logo.png +0 -0
  23. aedile-1.0.0/pyproject.toml +67 -0
  24. aedile-1.0.0/src/aedile/__init__.py +1 -0
  25. aedile-1.0.0/src/aedile/__main__.py +114 -0
  26. aedile-1.0.0/src/aedile/core/graph.py +228 -0
  27. aedile-1.0.0/src/aedile/core/models.py +86 -0
  28. aedile-1.0.0/src/aedile/core/optimizer.py +90 -0
  29. aedile-1.0.0/src/aedile/core/parser.py +234 -0
  30. aedile-1.0.0/src/aedile/core/rules/__init__.py +17 -0
  31. aedile-1.0.0/src/aedile/core/rules/base.py +23 -0
  32. aedile-1.0.0/src/aedile/core/rules/boundary.py +65 -0
  33. aedile-1.0.0/src/aedile/core/rules/cycle.py +64 -0
  34. aedile-1.0.0/src/aedile/core/rules/dead_code.py +118 -0
  35. aedile-1.0.0/src/aedile/core/rules/duplicate.py +106 -0
  36. aedile-1.0.0/src/aedile/core/rules/layer.py +87 -0
  37. aedile-1.0.0/src/aedile/core/rules/naming.py +84 -0
  38. aedile-1.0.0/src/aedile/core/scanner.py +205 -0
  39. aedile-1.0.0/src/aedile/core/similarity.py +168 -0
  40. aedile-1.0.0/src/aedile/core/verifier.py +149 -0
  41. aedile-1.0.0/src/aedile/infrastructure/cache.py +133 -0
  42. aedile-1.0.0/src/aedile/mcp/server.py +239 -0
  43. aedile-1.0.0/src/aedile/shared/config.py +201 -0
  44. aedile-1.0.0/src/aedile/shared/errors.py +34 -0
  45. aedile-1.0.0/src/aedile/shared/logging.py +28 -0
  46. aedile-1.0.0/templates/pre-commit-config.yaml +11 -0
  47. aedile-1.0.0/tests/test_config.py +66 -0
  48. aedile-1.0.0/tests/test_mcp.py +225 -0
  49. aedile-1.0.0/tests/test_parser_and_graph.py +119 -0
  50. aedile-1.0.0/tests/test_rules.py +216 -0
  51. aedile-1.0.0/tests/test_scanner_and_engines.py +93 -0
  52. aedile-1.0.0/tests/test_uncovered.py +91 -0
@@ -0,0 +1,31 @@
1
+ ---
2
+ name: 🐛 Bug Report
3
+ about: Create a report to help us improve Aedile
4
+ title: '[BUG] '
5
+ labels: bug
6
+ assignees: ''
7
+
8
+ ---
9
+
10
+ ### Describe the Bug
11
+ A clear and concise description of what the bug is.
12
+
13
+ ### To Reproduce
14
+ Steps to reproduce the behavior:
15
+ 1. Run command '...'
16
+ 2. See error '...'
17
+
18
+ ### Expected Behavior
19
+ A clear and concise description of what you expected to happen.
20
+
21
+ ### Screenshots / Console Output
22
+ If applicable, add screenshots or copy-paste terminal outputs (with `--verbose` enabled if possible) to help explain your problem.
23
+
24
+ ### Environment Context
25
+ - **Aedile Version**: [e.g., 1.0.0]
26
+ - **Python Version**: [e.g., 3.11.4]
27
+ - **OS**: [e.g., Windows 11, macOS Sonoma, Ubuntu 22.04]
28
+ - **Ecosystem tools**: [e.g., uv, poetry, pip, pre-commit]
29
+
30
+ ### Additional Context
31
+ Add any other context about the problem here (e.g. details about your codebase import structure).
@@ -0,0 +1,20 @@
1
+ ---
2
+ name: 🚀 Feature Request
3
+ about: Suggest an idea or new architectural rule for Aedile
4
+ title: '[FEATURE] '
5
+ labels: enhancement
6
+ assignees: ''
7
+
8
+ ---
9
+
10
+ ### Is your feature request related to a problem?
11
+ A clear and concise description of what the problem is. Ex. "I'm frustrated when [...]"
12
+
13
+ ### Describe the Solution You'd Like
14
+ A clear and concise description of what you want to happen. Explain how the proposed feature fits into Aedile's Clean Architecture structure.
15
+
16
+ ### Describe Alternatives You've Considered
17
+ A clear and concise description of any alternative solutions or features you've considered.
18
+
19
+ ### Additional Context
20
+ Add any other context, code mockups, or diagrams about the feature request here.
@@ -0,0 +1,17 @@
1
+ ## Description
2
+ Describe the changes introduced by this PR. Detail the problem solved or the feature added, and how the changes map to Aedile's core architecture layers.
3
+
4
+ ## Type of Change
5
+ - [ ] Bug fix (non-breaking change which fixes an issue)
6
+ - [ ] New feature (non-breaking change which adds functionality)
7
+ - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
8
+ - [ ] Documentation update (no code changes)
9
+
10
+ ## Checklist
11
+ - [ ] I have read the [CONTRIBUTING.md](CONTRIBUTING.md) document.
12
+ - [ ] My code follows the code style rules checked by `ruff`.
13
+ - [ ] My code passes all strict typing checks via `mypy`.
14
+ - [ ] I have added unit/integration tests that cover my changes.
15
+ - [ ] All new and existing tests passed via `pytest`.
16
+ - [ ] Test coverage meets or exceeds 95%.
17
+ - [ ] I have updated the documentation (`README.md`, `docs/`) to reflect these changes if applicable.
@@ -0,0 +1,69 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches:
6
+ - main
7
+ - release/v1.0-validation
8
+
9
+ pull_request:
10
+ branches:
11
+ - main
12
+
13
+ workflow_dispatch:
14
+
15
+
16
+ jobs:
17
+ test:
18
+ name: Test (Python ${{ matrix.python-version }} on ${{ matrix.os }})
19
+ runs-on: ${{ matrix.os }}
20
+ strategy:
21
+ fail-fast: false
22
+ matrix:
23
+ include:
24
+ # Full matrix on Ubuntu
25
+ - os: ubuntu-latest
26
+ python-version: "3.11"
27
+ - os: ubuntu-latest
28
+ python-version: "3.12"
29
+ - os: ubuntu-latest
30
+ python-version: "3.13"
31
+ - os: ubuntu-latest
32
+ python-version: "3.14"
33
+ # Latest stable version on Windows & macOS
34
+ - os: windows-latest
35
+ python-version: "3.13"
36
+ - os: macos-latest
37
+ python-version: "3.13"
38
+
39
+ steps:
40
+ - uses: actions/checkout@v4
41
+
42
+ - name: Set up Python ${{ matrix.python-version }}
43
+ uses: actions/setup-python@v5
44
+ with:
45
+ python-version: ${{ matrix.python-version }}
46
+ cache: 'pip'
47
+ cache-dependency-path: 'pyproject.toml'
48
+
49
+ - name: Install dependencies
50
+ run: |
51
+ python -m pip install --upgrade pip
52
+ pip install -e .
53
+ pip install pytest pytest-cov mypy ruff
54
+
55
+ - name: Run Ruff Lint check
56
+ run: ruff check .
57
+
58
+ - name: Run Ruff Format check
59
+ run: ruff format --check .
60
+
61
+ - name: Run Mypy Type check
62
+ run: mypy src/
63
+
64
+ - name: Run Pytest Suite
65
+ run: pytest --cov=src --cov-report=xml
66
+
67
+ - name: Verify Aedile CLI Rule Compiler
68
+ run: python -m aedile compile-rules
69
+
@@ -0,0 +1,121 @@
1
+ # ==============================================================================
2
+ # Aedile - Production-Grade .gitignore
3
+ # Matches best practices of Ruff, uv, FastAPI, and Requests.
4
+ # ==============================================================================
5
+
6
+ # ------------------------------------------------------------------------------
7
+ # Python Runtime & Caching
8
+ # ------------------------------------------------------------------------------
9
+ __pycache__/
10
+ *.py[cod]
11
+ *$py.class
12
+ *.so
13
+ .Python
14
+ build/
15
+ develop-eggs/
16
+ dist/
17
+ downloads/
18
+ eggs/
19
+ .eggs/
20
+ lib/
21
+ lib64/
22
+ parts/
23
+ sdist/
24
+ var/
25
+ wheels/
26
+ share/python-wheels/
27
+ *.egg-info/
28
+ .installed.cfg
29
+ *.egg
30
+ MANIFEST
31
+
32
+ # ------------------------------------------------------------------------------
33
+ # Virtual Environments
34
+ # ------------------------------------------------------------------------------
35
+ .venv/
36
+ venv/
37
+ ENV/
38
+ env/
39
+ /bin/
40
+ /include/
41
+ /lib/
42
+ /lib64/
43
+ /share/
44
+ /local/
45
+
46
+ # ------------------------------------------------------------------------------
47
+ # Testing, Coverage & Static Analysis
48
+ # ------------------------------------------------------------------------------
49
+ .pytest_cache/
50
+ .mypy_cache/
51
+ .ruff_cache/
52
+ .pyre/
53
+ .tox/
54
+ .nox/
55
+ .coverage
56
+ .coverage.*
57
+ coverage.xml
58
+ htmlcov/
59
+ nosetests.xml
60
+ pip-log.txt
61
+ pip-delete-this-directory.txt
62
+
63
+ # ------------------------------------------------------------------------------
64
+ # Editor & IDE Settings (VS Code, Cursor, JetBrains)
65
+ # ------------------------------------------------------------------------------
66
+ .idea/
67
+ .vscode/
68
+ .cursor/
69
+ *.suo
70
+ *.ntvs*
71
+ *.njsproj
72
+ *.sln
73
+ *.sw?
74
+ *.bak
75
+ *.tmp
76
+
77
+ # ------------------------------------------------------------------------------
78
+ # Operating System Artifacts (macOS, Windows, Linux)
79
+ # ------------------------------------------------------------------------------
80
+ .DS_Store
81
+ .DS_Store?
82
+ ._*
83
+ .Spotlight-V100
84
+ .Trashes
85
+ ehthumbs.db
86
+ Thumbs.db
87
+ Desktop.ini
88
+
89
+ # ------------------------------------------------------------------------------
90
+ # Environment Variables & Logs
91
+ # ------------------------------------------------------------------------------
92
+ .env
93
+ .env.*
94
+ *.log
95
+
96
+ # ------------------------------------------------------------------------------
97
+ # Benchmarks, Profiling & Reports
98
+ # ------------------------------------------------------------------------------
99
+ benchmarks/generated/
100
+ benchmarks/*.json.tmp
101
+ benchmarks/*.html
102
+ benchmarks/prof/
103
+ *.prof
104
+ *.flame
105
+ reports/
106
+ /reports/
107
+ *.html
108
+
109
+ # ------------------------------------------------------------------------------
110
+ # Explicit Track Rules (Do NOT Ignore)
111
+ # ------------------------------------------------------------------------------
112
+ !README.md
113
+ !LICENSE
114
+ !SECURITY.md
115
+ !CODE_OF_CONDUCT.md
116
+ !CONTRIBUTING.md
117
+ !docs/
118
+ !benchmarks/results.json
119
+ !images/logo.png
120
+ !examples/
121
+ !.github/
@@ -0,0 +1,37 @@
1
+ # Contributor Covenant Code of Conduct
2
+
3
+ ## Our Pledge
4
+
5
+ We as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
6
+
7
+ We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
8
+
9
+ ## Our Standards
10
+
11
+ Examples of behavior that contributes to a positive environment for our community include:
12
+
13
+ * Demonstrating empathy and kindness toward other people
14
+ * Being respectful of differing opinions, viewpoints, and experiences
15
+ * Giving and gracefully accepting constructive feedback
16
+ * Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
17
+ * Focusing on what is best for the overall community, not just for us as individuals
18
+
19
+ Examples of unacceptable behavior include:
20
+
21
+ * The use of sexualized language or imagery, and unwelcome sexual attention or advances
22
+ * Trolling, insulting or derogatory comments, and personal or political attacks
23
+ * Public or private harassment
24
+ * Publishing others' private information, such as a physical or email address, without their explicit permission
25
+ * Other conduct which could reasonably be considered inappropriate in a professional setting
26
+
27
+ ## Enforcement Responsibilities
28
+
29
+ Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior they deem inappropriate, threatening, offensive, or harmful.
30
+
31
+ ## Scope
32
+
33
+ This Code of Conduct applies within all project spaces, and also applies when an individual is officially representing the project or its community in public spaces.
34
+
35
+ ## Attribution
36
+
37
+ This Code of Conduct is adapted from the Contributor Covenant, version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
@@ -0,0 +1,44 @@
1
+ # Contributing to Aedile
2
+
3
+ We welcome contributions to Aedile! To ensure code quality, speed, and safety, we ask contributors to follow these guidelines.
4
+
5
+ ## Development Setup
6
+
7
+ 1. Clone the repository and navigate to the project directory.
8
+ 2. Initialize virtual environment:
9
+ ```bash
10
+ python -m venv .venv
11
+ source .venv/bin/activate # On Windows: .venv\Scripts\activate
12
+ ```
13
+ 3. Install the project in editable mode with development dependencies:
14
+ ```bash
15
+ pip install -e .
16
+ pip install pytest pytest-cov mypy ruff pre-commit
17
+ ```
18
+
19
+ ## Development Quality Gate
20
+
21
+ Before submitting a Pull Request, please run the following checks locally:
22
+
23
+ ### 1. Formatting & Linting
24
+ We use `ruff` to enforce coding style and imports formatting.
25
+ ```bash
26
+ ruff check src/ tests/
27
+ ```
28
+
29
+ ### 2. Static Typing
30
+ We use `mypy` for strict typechecking:
31
+ ```bash
32
+ mypy src/
33
+ ```
34
+
35
+ ### 3. Testing
36
+ We use `pytest` for unit and integration tests. All PRs must maintain or improve test coverage (>95%):
37
+ ```bash
38
+ pytest --cov=src --cov-report=term-missing tests/
39
+ ```
40
+
41
+ ## Pull Request Guidelines
42
+ - Follow [Conventional Commits](https://www.conventionalcommits.org/) for your commit messages.
43
+ - Ensure all tests and GitHub workflows pass.
44
+ - Update documentation in the `docs/` folder if changing behavior or config settings.
aedile-1.0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Aaryan Rawat
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
aedile-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,134 @@
1
+ Metadata-Version: 2.4
2
+ Name: aedile
3
+ Version: 1.0.0
4
+ Summary: Maintains architectural integrity as AI writes code.
5
+ Author-email: Aaryan Rawat <aaryan.rawat@example.com>
6
+ License: MIT
7
+ License-File: LICENSE
8
+ Classifier: Development Status :: 5 - Production/Stable
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: License :: OSI Approved :: MIT License
11
+ Classifier: Programming Language :: Python :: 3.11
12
+ Classifier: Programming Language :: Python :: 3.12
13
+ Classifier: Programming Language :: Python :: 3.13
14
+ Classifier: Programming Language :: Python :: 3.14
15
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
16
+ Classifier: Topic :: Software Development :: Quality Assurance
17
+ Requires-Python: >=3.11
18
+ Description-Content-Type: text/markdown
19
+
20
+ <p align="center">
21
+ <img src="images/logo.png" alt="Aedile Logo" width="180"/>
22
+ </p>
23
+
24
+ # Aedile
25
+
26
+ > Before an AI writes code, it should prove that the code deserves to exist.
27
+
28
+ **Aedile** is an engineering intelligence layer for AI coding assistants. Running locally as a zero-dependency Model Context Protocol (MCP) server, it intercepts implementation plans before code generation begins—guiding assistants to reuse existing patterns, leverage standard libraries, and respect layer boundaries.
29
+
30
+ [![CI](https://github.com/aaryanrwt/aedile/actions/workflows/ci.yml/badge.svg)](https://github.com/aaryanrwt/aedile/actions/workflows/ci.yml)
31
+ [![Python Version](https://img.shields.io/badge/python-%3E%3D3.11-blue.svg)](https://www.python.org/)
32
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
33
+
34
+ ---
35
+
36
+ ## 1. Quick Start
37
+
38
+ Install the package directly from GitHub:
39
+ ```bash
40
+ pip install git+https://github.com/aaryanrwt/aedile.git
41
+ ```
42
+
43
+ Generate the local prompt rulesets (`.cursorrules` and `.claudeprompt` templates):
44
+ ```bash
45
+ python -m aedile compile-rules
46
+ ```
47
+
48
+ Add the MCP server command `python -m aedile` to your coding assistant (e.g. Cursor or Claude Code). See [SUPPORTED_AGENTS.md](SUPPORTED_AGENTS.md) for step-by-step setup guides.
49
+
50
+ ---
51
+
52
+ ## 2. Quick Example: Adding JWT Token Generation
53
+
54
+ ### Standard AI Assistant
55
+ The assistant plans to write a custom JWT helper, unaware that `src/shared/auth.py` already contains a token generator. It installs a new library, adds 40 lines of wrapper code, and increases reasoning costs.
56
+
57
+ ### With Aedile
58
+ The assistant consults Aedile during its planning step:
59
+
60
+ ```text
61
+ AI: "I'm going to create jwt.py."
62
+ Aedile: "Existing helper found: src/shared/auth.py. Reuse create_token()."
63
+ AI: "Understood. Importing src.shared.auth and writing 1 line instead of 40."
64
+ ```
65
+
66
+ By querying Aedile, the assistant avoids duplicate implementations, preserves the codebase architecture, and reduces reasoning token usage.
67
+
68
+ ---
69
+
70
+ ## 3. How it Works
71
+
72
+ Aedile hooks into the assistant's planning loop via the Model Context Protocol (MCP). Before code is written, Aedile evaluates the proposed changes:
73
+
74
+ ```mermaid
75
+ graph TD
76
+ A[User Prompt] --> B[AI Assistant Plans Change]
77
+ B --> C{Aedile Consult Tool}
78
+ C -->|Scan Symbols| D[Similarity & Reuse Check]
79
+ C -->|Analyze Imports| E[Cycle & Boundary Check]
80
+ D --> F[Consolidated Advice]
81
+ E --> F
82
+ F --> G[Assistant Generates Optimal Code]
83
+ ```
84
+
85
+ We designed Aedile to enforce a structured [Decision Ladder](docs/DECISION_LADDER.md)—directing the assistant to check codebase reuse, standard libraries, and pre-installed dependencies before drafting new logic.
86
+
87
+ ---
88
+
89
+ ## 4. Benchmarks
90
+
91
+ We measured the execution of backend engineering tasks (such as token authentication and endpoint refactoring) across multiple runs. Full parameters are documented in [results.json](benchmarks/results.json) and compiled in [BENCHMARKS.md](benchmarks/BENCHMARKS.md).
92
+
93
+ | Metric | Without Aedile | Prompt-Only Rules | With Aedile |
94
+ | :--- | :---: | :---: | :---: |
95
+ | **Reasoning Cost (Avg Tokens)** | 1,850 | 1,100 | **350** |
96
+ | **Context Window Size (Tokens)** | 4,200 | 5,100 | **1,200** |
97
+ | **Duplicate Code Written** | Yes | Yes | **No** |
98
+ | **Tool Calls Executed** | 3 | 2 | **1** |
99
+
100
+ ---
101
+
102
+ ## 5. Paradigm Comparison
103
+
104
+ Aedile represents a shift in how codebase constraints are enforced:
105
+
106
+ * **Static Prompting vs. Dynamic Context**: Static prompts (like `.cursorrules` text) decay and suffer from "prompt drift" in long sessions. Aedile queries real-time codebase symbols and active dependencies dynamically via a single MCP tool (`aedile_consult`).
107
+ * **Post-Facto Linters vs. In-Plan Verification**: Traditional linters check imports after files are saved, failing in CI/CD. Aedile verifies planned imports in-memory before files are written, letting the model self-correct.
108
+
109
+ ### Trade-offs & Limitations
110
+ Aedile intentionally trades process startup latency (~100ms) for dynamic codebase verification. We optimized traversal by using SHA-256 increment caching, keeping scan times under 40ms. Symbol parsing is currently optimized for Python workspaces, with TypeScript/JavaScript support planned next.
111
+
112
+ ---
113
+
114
+ ## 6. Frequently Asked Questions
115
+
116
+ ### Why not just use static prompting (e.g., Ponytail)?
117
+ Static system prompts are helpful for basic guidelines but decay as the context window grows. AI models suffer from "prompt drift" and will ignore static text. Aedile enforces constraints dynamically through a tool interface, returning real-time repository facts directly into the assistant's context.
118
+
119
+ ### Does it require internet access?
120
+ No. Aedile is fully offline-first. Repository scans, symbol indexing, and graph simulation run locally on your machine.
121
+
122
+ ---
123
+
124
+ ## 7. Contributing & License
125
+
126
+ We welcome contributions to Aedile. Please review our [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
127
+
128
+ Aedile is open-source software licensed under the [MIT License](LICENSE).
129
+
130
+ ---
131
+
132
+ ## Star History
133
+
134
+ [![Star History Chart](https://api.star-history.com/svg?repos=aaryanrwt/aedile&type=Date)](https://star-history.com/#aaryanrwt/aedile&Date)
aedile-1.0.0/README.md ADDED
@@ -0,0 +1,115 @@
1
+ <p align="center">
2
+ <img src="images/logo.png" alt="Aedile Logo" width="180"/>
3
+ </p>
4
+
5
+ # Aedile
6
+
7
+ > Before an AI writes code, it should prove that the code deserves to exist.
8
+
9
+ **Aedile** is an engineering intelligence layer for AI coding assistants. Running locally as a zero-dependency Model Context Protocol (MCP) server, it intercepts implementation plans before code generation begins—guiding assistants to reuse existing patterns, leverage standard libraries, and respect layer boundaries.
10
+
11
+ [![CI](https://github.com/aaryanrwt/aedile/actions/workflows/ci.yml/badge.svg)](https://github.com/aaryanrwt/aedile/actions/workflows/ci.yml)
12
+ [![Python Version](https://img.shields.io/badge/python-%3E%3D3.11-blue.svg)](https://www.python.org/)
13
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
14
+
15
+ ---
16
+
17
+ ## 1. Quick Start
18
+
19
+ Install the package directly from GitHub:
20
+ ```bash
21
+ pip install git+https://github.com/aaryanrwt/aedile.git
22
+ ```
23
+
24
+ Generate the local prompt rulesets (`.cursorrules` and `.claudeprompt` templates):
25
+ ```bash
26
+ python -m aedile compile-rules
27
+ ```
28
+
29
+ Add the MCP server command `python -m aedile` to your coding assistant (e.g. Cursor or Claude Code). See [SUPPORTED_AGENTS.md](SUPPORTED_AGENTS.md) for step-by-step setup guides.
30
+
31
+ ---
32
+
33
+ ## 2. Quick Example: Adding JWT Token Generation
34
+
35
+ ### Standard AI Assistant
36
+ The assistant plans to write a custom JWT helper, unaware that `src/shared/auth.py` already contains a token generator. It installs a new library, adds 40 lines of wrapper code, and increases reasoning costs.
37
+
38
+ ### With Aedile
39
+ The assistant consults Aedile during its planning step:
40
+
41
+ ```text
42
+ AI: "I'm going to create jwt.py."
43
+ Aedile: "Existing helper found: src/shared/auth.py. Reuse create_token()."
44
+ AI: "Understood. Importing src.shared.auth and writing 1 line instead of 40."
45
+ ```
46
+
47
+ By querying Aedile, the assistant avoids duplicate implementations, preserves the codebase architecture, and reduces reasoning token usage.
48
+
49
+ ---
50
+
51
+ ## 3. How it Works
52
+
53
+ Aedile hooks into the assistant's planning loop via the Model Context Protocol (MCP). Before code is written, Aedile evaluates the proposed changes:
54
+
55
+ ```mermaid
56
+ graph TD
57
+ A[User Prompt] --> B[AI Assistant Plans Change]
58
+ B --> C{Aedile Consult Tool}
59
+ C -->|Scan Symbols| D[Similarity & Reuse Check]
60
+ C -->|Analyze Imports| E[Cycle & Boundary Check]
61
+ D --> F[Consolidated Advice]
62
+ E --> F
63
+ F --> G[Assistant Generates Optimal Code]
64
+ ```
65
+
66
+ We designed Aedile to enforce a structured [Decision Ladder](docs/DECISION_LADDER.md)—directing the assistant to check codebase reuse, standard libraries, and pre-installed dependencies before drafting new logic.
67
+
68
+ ---
69
+
70
+ ## 4. Benchmarks
71
+
72
+ We measured the execution of backend engineering tasks (such as token authentication and endpoint refactoring) across multiple runs. Full parameters are documented in [results.json](benchmarks/results.json) and compiled in [BENCHMARKS.md](benchmarks/BENCHMARKS.md).
73
+
74
+ | Metric | Without Aedile | Prompt-Only Rules | With Aedile |
75
+ | :--- | :---: | :---: | :---: |
76
+ | **Reasoning Cost (Avg Tokens)** | 1,850 | 1,100 | **350** |
77
+ | **Context Window Size (Tokens)** | 4,200 | 5,100 | **1,200** |
78
+ | **Duplicate Code Written** | Yes | Yes | **No** |
79
+ | **Tool Calls Executed** | 3 | 2 | **1** |
80
+
81
+ ---
82
+
83
+ ## 5. Paradigm Comparison
84
+
85
+ Aedile represents a shift in how codebase constraints are enforced:
86
+
87
+ * **Static Prompting vs. Dynamic Context**: Static prompts (like `.cursorrules` text) decay and suffer from "prompt drift" in long sessions. Aedile queries real-time codebase symbols and active dependencies dynamically via a single MCP tool (`aedile_consult`).
88
+ * **Post-Facto Linters vs. In-Plan Verification**: Traditional linters check imports after files are saved, failing in CI/CD. Aedile verifies planned imports in-memory before files are written, letting the model self-correct.
89
+
90
+ ### Trade-offs & Limitations
91
+ Aedile intentionally trades process startup latency (~100ms) for dynamic codebase verification. We optimized traversal by using SHA-256 increment caching, keeping scan times under 40ms. Symbol parsing is currently optimized for Python workspaces, with TypeScript/JavaScript support planned next.
92
+
93
+ ---
94
+
95
+ ## 6. Frequently Asked Questions
96
+
97
+ ### Why not just use static prompting (e.g., Ponytail)?
98
+ Static system prompts are helpful for basic guidelines but decay as the context window grows. AI models suffer from "prompt drift" and will ignore static text. Aedile enforces constraints dynamically through a tool interface, returning real-time repository facts directly into the assistant's context.
99
+
100
+ ### Does it require internet access?
101
+ No. Aedile is fully offline-first. Repository scans, symbol indexing, and graph simulation run locally on your machine.
102
+
103
+ ---
104
+
105
+ ## 7. Contributing & License
106
+
107
+ We welcome contributions to Aedile. Please review our [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
108
+
109
+ Aedile is open-source software licensed under the [MIT License](LICENSE).
110
+
111
+ ---
112
+
113
+ ## Star History
114
+
115
+ [![Star History Chart](https://api.star-history.com/svg?repos=aaryanrwt/aedile&type=Date)](https://star-history.com/#aaryanrwt/aedile&Date)
@@ -0,0 +1,18 @@
1
+ # Security Policy
2
+
3
+ ## Supported Versions
4
+
5
+ We actively support and patch the latest major release of Aedile.
6
+
7
+ | Version | Supported |
8
+ | :--- | :---: |
9
+ | 1.0.x | Yes |
10
+ | < 1.0.0 | No |
11
+
12
+ ## Reporting a Vulnerability
13
+
14
+ If you discover a security vulnerability in Aedile, please do not disclose it publicly. Instead, report it directly to the maintainers:
15
+
16
+ * Email: security@aedile.dev (or open a private security draft advisory on GitHub)
17
+
18
+ We will acknowledge your report within 48 hours and work with you to patch the issue and publish a CVE if appropriate.