sultan9723/AegisNex / .agents/skills/ci-pipeline
ci-pipeline
VerifiedPatterns for debugging and extending the AegisNex GitHub Actions CI pipeline. Covers common failure modes, encoding issues, dependency problems, and how to add new CI steps.
| File | Kind | Size |
|---|---|---|
| LICENSE.txt | markdown | 1.1 KB |
| SKILL.md | skill md | 4.4 KB |
SKILL.md
View on GitHub---
name: ci-pipeline
description: Patterns for debugging and extending the AegisNex GitHub Actions CI pipeline. Covers common failure modes, encoding issues, dependency problems, and how to add new CI steps.
license: Complete terms in LICENSE.txt
---
# CI Pipeline
You are the CI engineer for AegisNex. When a pipeline fails, you diagnose the root cause systematically rather than guessing. The pipeline lives at `.github/workflows/pipeline.yml` and runs on every push to `main` and every pull request.
## Pipeline structure
The current pipeline runs on `ubuntu-latest` with Python 3.12:
1. `actions/checkout@v4` -- clones the repo
2. `actions/setup-python@v5` -- installs Python 3.12
3. `pip install -r requirements.txt` -- installs dependencies
4. `pytest -x -vv` -- runs tests, stops on first failure
## Common failure modes
### 1. File encoding issues (BOM)
**Symptom:** `ERROR: unexpected line: '\ufeff[pytest]'` or similar parse errors on config files.
**Cause:** File saved with UTF-8 BOM (`\xef\xbb\xbf`) instead of plain UTF-8. Windows editors sometimes add BOM automatically.
**Fix:** Rewrite the file without BOM. Verify with:
```python
with open("filename.ini", "rb") as f:
raw = f.read(3)
assert raw != b"\xef\xbb\xbf", "BOM detected"
```
**Prevention:** The repo has `.editorconfig` enforcing `charset = utf-8` and `.gitattributes` with `* text=auto eol=lf`. Never disable these.
### 2. Missing dependencies
**Symptom:** `ModuleNotFoundError: No module named X`
**Cause:** New dependency added to code but not to `requirements.txt`.
**Fix:** Add the dependency to `requirements.txt` with a pinned version. Check if it has C extensions that need system packages on Ubuntu.
### 3. Path mismatches
**Symptom:** Tests find wrong files, config not loaded, import errors.
**Cause:** Windows paths (`\`) vs Linux paths (`/`). Hardcoded absolute paths.
**Fix:** Always use `pathlib.Path` or `os.path.join()`. Never hardcode paths. The CI runs on Ubuntu -- test with `python -m pytest` locally on Linux or WSL.
### 4. Timeout
**Symptom:** `Error: Process completed with exit code 143` or job cancelled after 6 hours.
**Cause:** Test hangs, infinite loop, or deadlock.
**Fix:** Add timeout to the pytest step:
```yaml
- run: pytest -x -vv
timeout-minutes: 15
```
Check for unmocked network calls, blocking I/O in tests, or infinite loops in AI engine.
### 5. Import order / circular imports
**Symptom:** `ImportError: cannot import name X from partially initialized module Y`
**Cause:** Circular dependency between modules.
**Fix:** Move shared types to a separate module (`types.py` or `state.py`). Use TYPE_CHECKING imports for type hints. The intelligence engine uses lazy imports inside functions to avoid this -- follow that pattern.
### 6. Type checking failures
**Symptom:** `mypy: error: Incompatible types in assignment`
**Cause:** Type annotations do not match runtime usage.
**Fix:** Run `mypy src/` locally first. Use `# type: ignore[assignment]` only with a comment explaining why.
## How to add a new CI step
### Adding a linting step
```yaml
- name: Lint
run: |
pip install ruff
ruff check src/
```
### Adding a type checking step
```yaml
- name: Type check
run: |
pip install mypy
mypy src/ --ignore-missing-imports
```
### Adding a build verification step
```yaml
- name: Verify package
run: |
python -c "import src.dashboard"
python -c "import src.intelligence.graph"
```
## Debugging a failed CI run
1. Read the error message carefully -- the first error is usually the root cause.
2. Check the step that failed -- was it checkout, install, or test?
3. Reproduce locally -- run the exact same command on Linux (WSL or Docker).
4. Check file encoding -- if the error mentions unexpected characters, check for BOM.
5. Check paths -- if the error is FileNotFoundError, check for Windows vs Linux paths.
6. Check dependencies -- if ModuleNotFoundError, verify requirements.txt.
7. Check for hanging tests -- if timeout, add `--timeout=30` to pytest.
## AegisNex-specific CI considerations
- The AI engine imports are lazy (inside functions) to avoid loading LLM providers at import time. Do not change this pattern.
- SQLite databases (`ai_memory.db`, `aegisnex.db`) are created at runtime. Tests must not depend on pre-existing databases.
- Docker-dependent tests should be skipped in CI (`@pytest.mark.skipif`) unless Docker is available.
- The frontend (Next.js) is not tested in CI yet. Only Python tests run.Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |