sbadakhc
diff --git a/‎.claude/commands/commit-pr.md‎
Lines changed: 52 additions & 0 deletions b/‎.claude/commands/commit-pr.md‎
Lines changed: 52 additions & 0 deletions
diff --git a/‎.claude/rules/ci-checks.md‎
Lines changed: 56 additions & 0 deletions b/‎.claude/rules/ci-checks.md‎
Lines changed: 56 additions & 0 deletions
diff --git a/‎.claude/rules/formatting.md‎
Lines changed: 30 additions & 0 deletions b/‎.claude/rules/formatting.md‎
Lines changed: 30 additions & 0 deletions
diff --git a/‎.claude/rules/security.md‎
Lines changed: 32 additions & 0 deletions b/‎.claude/rules/security.md‎
Lines changed: 32 additions & 0 deletions
diff --git a/‎.claude/rules/workflow.md‎
Lines changed: 47 additions & 0 deletions b/‎.claude/rules/workflow.md‎
Lines changed: 47 additions & 0 deletions
diff --git a/‎.claude/settings.json‎
Lines changed: 29 additions & 0 deletions b/‎.claude/settings.json‎
Lines changed: 29 additions & 0 deletions
@@ -0,0 +1,52 @@
+---
+description: Commit changes and create a PR following AIXCL Issue-First workflow
+disable-model-invocation: true
+allowed-tools: Bash(git add *), Bash(git commit *), Bash(git push *), Bash(gh pr create *)
+---
+
+## Context
+
+- Current branch: !`git branch --show-current`
+- Current status: !`git status --short`
+- Recent commits: !`git log --oneline -5`
+
+## Your Task
+
+Based on the above changes:
+
+1. **Stage all changes** (if not already staged):
+   ```bash
+   git add .
+   ```
+
+2. **Create a conventional commit**:
+   - Format: `<type>: <description> (under 72 chars)`
+   - Reference issue: `Fixes #<issue-number>`
+   - Use `./scripts/utils/create-pr.sh` wrapper if available, or craft manually
+   - Example: `feat: Add CLAUDE.md for Claude Code compatibility`
+
+3. **Push the branch to origin**:
+   ```bash
+   git push -u origin <branch-name>
+   ```
+
+4. **Create a pull request** using `gh pr create` with:
+   - Title: `<description> (#<issue-number>)` (NO colons)
+   - Body: `Fixes #<issue-number>`
+   - Assignee: set at creation time (required by `pr-validation.yml`)
+   - Label: at least one `component:*` label (required by `pr-validation.yml`)
+
+   **IMPORTANT**: Pass `--assignee` and `--label` at creation time. Do NOT create then edit. The PR Validation workflow fires on the `opened` event. If assignee/label are not present at creation, the check will fail permanently.
+
+   ```bash
+   gh pr create --title "Description (#999)" --body "Fixes #999" --assignee <username> --label "component:infrastructure"
+   ```
+
+5. **Verify CI**: Monitor GitHub Actions and ensure all checks pass before completing.
+
+## Safety Rules
+
+- `git push --force` is **DENIED**
+- `rm -rf` operations require explicit human approval
+- Always reference the issue number in commits and PRs
+- All CI checks must be green before the task is complete
@@ -0,0 +1,56 @@
+# CI Checks and Compliance
+
+## Pre-Commit Checklist
+Before committing any changes, verify locally:
+
+### Shell Scripts
+- Run ShellCheck: `shellcheck --severity=warning --exclude=SC1091 <file.sh>`
+- Run syntax check: `bash -n <file.sh>`
+- Common failures: SC2034 (unused variables), SC2120 (function args), SC2086 (unquoted variables)
+
+### Markdown Files
+- No non-ASCII punctuation: no smart quotes, em dashes (--), en dashes (-), ellipsis (...), non-breaking spaces
+- Use plain ASCII equivalents: `--` for dashes, `...` for ellipsis, straight quotes
+- No CRLF line endings (use LF only)
+- No broken relative links (`./` or `../` paths must resolve)
+
+### YAML Files
+- Run: `yamllint -c .yamllint.yml <file.yml>`
+- Line length limit: 160 characters
+
+### Docker Compose Files
+- Run: `docker compose -f services/docker-compose.yml config > /dev/null`
+
+## PR Requirements (ALL must be set at creation time)
+```bash
+gh pr create \
+  --title "<description> (#<number>)" \
+  --body-file /tmp/pr-body.md \
+  --assignee <username> \
+  --label "component:<name>"
+```
+- Title: ends with `(#<number>)`, no colons
+- Assignee: required, set at creation (not after)
+- Label: at least one `component:*` label, set at creation (not after)
+- NEVER use two-step creation -- webhook fires on `opened` event, labels/assignee must be present
+
+## CI Workflows Summary
+
+| Workflow | Trigger | Key Checks |
+|----------|---------|------------|
+| pr-validation.yml | PR open/edit | Title format, assignee, component label |
+| bash-ci.yml | PR + push | check-env, CRLF, ASCII markdown |
+| quick-tests.yml | Push to dev (.sh files) | Security tests, bash -n, ./aixcl help |
+| security.yml | PR + push | ShellCheck (warning+, no SC1091), dependency review |
+| documentation-checks.yml | PR + push | check-paths.sh, check-generated-files.sh, yamllint, compose validate |
+| codeql.yml | PR + push | GitHub Actions workflow security (actions language only) |
+
+## Running Checks Locally
+```bash
+# Full pre-PR check
+bash scripts/checks/check-paths.sh
+bash scripts/checks/check-generated-files.sh
+shellcheck --severity=warning --exclude=SC1091 $(find . -name "*.sh" -not -path "./.git/*")
+yamllint -c .yamllint.yml .
+./aixcl utils check-env
+```
@@ -0,0 +1,30 @@
+# Formatting and Conventions
+
+## Titles
+- **Issues**: `[TYPE] Description` (e.g., `[TASK] Setup agent`, not `[TASK]: Setup agent`)
+- **PRs**: `Description (#<number>)` (e.g., `Setup agent template (#42)`, not `Setup: agent template (#42)`)
+- NO colons in issue or PR titles
+
+## Text
+- Use plain ASCII. No Unicode checkmarks, no emoji.
+  - **Exception**: Release notes may use `✅` (green checkmark) for visual checkbox indicators in GitHub release pages, where markdown `- [x]` does not render interactively.
+- Use markdown checkboxes: `- [x]` for completed, `- [ ]` for incomplete (for issues, PRs, and documentation)
+- Use Unix line endings (LF) -- CRLF is rejected by CI
+
+## Labels
+**Issue Types** (select exactly one): `Bug`, `Feature`, `Task`
+**Component Labels** (required): `component:runtime-core`, `component:ollama`, `component:persistence`, `component:observability`, `component:ui`, `component:cli`, `component:infrastructure`, `component:testing`
+**Priority** (optional): `P1`, `P2`, `P3`
+**Profile** (optional): `profile:bld`, `profile:sys`
+**Category** (optional): `Fix`, `Enhancement`, `Refactor`, `Maintenance`
+
+## Commits
+- Allowed types: `fix`, `feat`, `refactor`, `docs`, `test`, `chore`, `ci`
+- Reference issue: `Fixes #<n>` or `Addresses #<n>`
+- First line under 72 characters
+
+## Lazy-Loading
+Load files on a need-to-know basis:
+- Creating an issue → Read `.github/ISSUE_TEMPLATE/task.md` first
+- Creating a PR → Read `.github/PULL_REQUEST_TEMPLATE.md` first
+- Releasing → Read `CHANGELOG.md` to extract latest version entry
@@ -0,0 +1,32 @@
+# Security and Architecture Policy
+
+## Fixed Core Runtime (Non-Negotiable)
+- **Inference Engine** (Ollama) -- Docker-managed, always enabled
+- **OpenCode** -- AI-powered code assistance (VS Code plugin, client-side), always enabled
+- Never remove, replace, or conditionally disable runtime core components
+
+## Runtime vs Operational Services Boundary
+- Runtime core must be runnable **without** any operational services
+- Operational services may depend on runtime core
+- Runtime core must **never** depend on operational services
+
+## Safe Areas for AI Contribution
+**You MAY:**
+- Modify operational services (monitoring, logging, automation)
+- Improve documentation
+- Adjust CLI ergonomics (without changing semantics)
+- Organize Compose files (if invariants are preserved)
+- Add new operational profiles or tooling
+
+**You MUST NOT:**
+- Remove/replace/disable runtime core components
+- Introduce runtime core → operational service dependencies
+- Merge runtime logic with monitoring/admin tooling
+- Collapse service boundaries
+- Add external libraries, cloud services, telemetry, or analytics without explicit approval
+
+## Escalation
+1. If working on an issue → Post clarification as issue comment
+2. If no issue exists → Ask human operator directly; do not create issue unilaterally
+3. If security concern → Flag with `[SECURITY]` prefix and await explicit approval
+4. If authority conflict → Document override request and obtain explicit confirmation
@@ -0,0 +1,47 @@
+# Issue-First Workflow
+
+## Core Rule
+Always create an issue before starting work. Every code change, fix, or feature must be traceable to a GitHub issue.
+
+## Step-by-Step
+
+1. **Create Issue**
+   - Title format: `[TYPE] Description` (e.g., `[TASK]`, `[BUG]`, `[FEATURE]`)
+   - NO colons in titles
+   - Use plain ASCII markdown (`- [x]` checkboxes, not Unicode)
+   - Add labels: component (required), priority (optional), profile (optional)
+   - Always assign the issue
+
+2. **Create Branch**
+   - Format: `issue-<number>/<short-description>`
+   - Example: `issue-217/fix-encoding-problem`
+   - Always branch from `dev`
+
+3. **Make Changes**
+   - Small, reversible steps
+   - Follow project conventions
+   - Run lint checks if modifying agent/action files
+
+4. **Commit**
+   - Format: `<type>: <description>` (under 72 chars)
+   - Reference issue: `Fixes #<issue-number>`
+   - Use bullet points for multiple changes
+
+5. **Push and Create PR**
+   - Title format: `<description> (#<number>)` (no colons)
+   - PR body must reference issue: `Fixes #<number>`
+   - Add matching labels to PR
+   - Always assign the PR
+
+6. **Verify CI**
+   - Check GitHub Actions status
+   - All status checks must be green before completing
+
+## Branch Strategy
+
+| Branch | Purpose |
+|--------|---------|
+| `main` | Production-ready code |
+| `dev` | Active development, feature integration |
+
+Correct flow: `Feature Branch -> dev -> main`
@@ -0,0 +1,29 @@
+{
+  "permissions": {
+    "edit": "ask",
+    "bash": {
+      "allowed": [
+        "git status*",
+        "git diff*",
+        "git log*",
+        "ls*",
+        "cat*",
+        "grep*",
+        "gh repo*",
+        "gh issue*",
+        "./scripts/checks/check-agents.sh*"
+      ],
+      "ask": [
+        "git add*",
+        "git commit*",
+        "git push*",
+        "gh pr create*"
+      ],
+      "denied": [
+        "rm -rf*",
+        "git push --force*"
+      ]
+    },
+    "webfetch": "ask"
+  }
+}