Critical Evaluation: Proposals & Optimizations for the Agentic Dev Environment

.agents/skills/find-skills/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query] [--owner <owner>]` - Search for skills interactively or by keyword, optionally scoped to a GitHub owner
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Check the Leaderboard First
+
+Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
+
+For example, top skills for web development include:
+- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
+- `anthropics/skills` — Frontend design, document processing (100K+ installs)
+
+### Step 3: Search for Skills
+
+If the leaderboard doesn't cover the user's need, run the find command:
+
+```bash
+npx skills find [query] [--owner <owner>]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+### Step 4: Verify Quality Before Recommending
+
+**Do not recommend a skill based solely on search results.** Always verify:
+
+1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
+2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
+3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
+
+### Step 5: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install count and source
+3. The install command they can run
+4. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+(185K installs)
+
+To install it:
+npx skills add vercel-labs/agent-skills@react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
+```
+
+### Step 6: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```

.replit

@@ -0,0 +1,7 @@
+modules = ["python-3.12", "bash", "web", "nodejs-20", "rust-stable"]
+
+[nix]
+channel = "stable-25_05"
+
+[agent]
+expertMode = true

replit.md

@@ -0,0 +1,182 @@
+# ArchWiz Monorepo — Critical Evaluation & Roadmap
+
+> Evaluated: 2026-07-31. Stack: Python 3 / Bash / Rust (harmonizer) / TypeScript (commingle-swarm). Origin: Termux/Android monorepo.
+
+---
+
+## What This Is
+
+A personal **agentic development environment** built around the DeepSeek AI API. The system closes a loop: the user chats with DeepSeek via a terminal CLI (`deepcli`), the ArchWiz cockpit auto-detects and executes code blocks from those conversations, results feed back into the knowledge graph, and a suite of forensic/verification tools (Sentinel, Archivist, Mirror, Dangle Detector) maintain quality and provenance.
+
+### Pipeline Flow (high-level)
+```
+User → DeepSeek (via deepcli TUI / cli.py)
+  → core.py stream_completion() → session cache (~/.deepcli/session_store/)
+    → dispatch_pipeline.py (called on every cache write, via core.py hook)
+      → autonomous_runner.py / dispatch_task.py (sandboxed execution)
+        → Sentinel (5-gate verification: file integrity, naming, duplicate, probe, shockwave)
+          → promote.py (ascension to true_versions)
+  → cli-synthegration (exports, versions, branches conversation history)
+    → Chronos / time_loop_accelerator (success-only trunk management)
+  → archwiz/archivist.py (query engine over all indices)
+```
+
+> **Note:** `export_poller.sh` and `activity_listener.py` are legacy execution paths — the canonical code-block execution flow runs through the TUI and `core.py`'s cache-write hook (`dispatch_pipeline.py`). The poller/listener represent an earlier, now-superseded approach and should be treated as candidates for removal or archival rather than maintained in parallel.
+
+---
+
+## How to Run (on Replit)
+
+Most tools **cannot run as-is** on Replit — see the Termux coupling issue below. Once that is resolved, the entry point is:
+
+```bash
+python3 archwiz/archwiz.py        # Main cockpit (TUI menu)
+python3 deepcli/deepcli.py new    # Start a new DeepSeek session
+python3 deepcli/deepcli.py send "prompt here"
+```
+
+The DeepSeek integration requires a valid `ds_session_id` cookie and bearer token extracted from a browser session (see `deepcli/extract-token.js`).
+
+---
+
+## Critical Issues (Must Fix)
+
+### 1. Termux Path Coupling — Blocks Everything
+Almost all `subprocess.run(...)` calls in `archwiz/archwiz.py` use `os.path.expanduser('~/archwiz/...')`, which correctly resolves to `/home/runner/archwiz/...` on Replit. However:
+
+- `archwiz/archwiz.sh` has a hardcoded Termux shebang: `/data/data/com.termux/files/usr/bin/bash`
+- `cli-synthegration/workspace/reference/token_provider.py:5` hardcodes `/data/data/com.termux/files/home/deepcli`
+- Top-level `enforce_hierarchy.sh` is a broken symlink → `/data/data/com.termux/files/home/workspace/scripts/enforce_workspace_hierarchy.sh`
+- Many top-level symlinks (e.g., `dispatch_task.py`, `agent_shell.py`, `archaeologist.py`) point into the Termux filesystem — silently broken on Replit
+- Large archive files (`archwiz/pointer_inverted.json`, session logs) contain historical Termux paths — low priority but confusing
+
+> **Key constraint:** Pure relative paths are not a safe fix here — the tools are invoked from different working directories (cockpit, listener, dispatch, TUI), so a relative path resolves differently depending on the call site. The correct solution is an **environment-aware intermediary layer**, not relative paths.
+
+**Fix:** Create `archwiz/config.py` as a single source of truth for all paths, resolved at import time via an environment variable:
+
+```python
+# archwiz/config.py
+import os
+from pathlib import Path
+
+# Set ARCHWIZ_ENV=termux | replit | local (auto-detected if unset)
+_env = os.environ.get('ARCHWIZ_ENV', '').lower()
+if not _env:
+    _env = 'termux' if Path('/data/data/com.termux').exists() else 'replit'
+
+if _env == 'termux':
+    ARCHWIZ_ROOT = Path('/data/data/com.termux/files/home')
+else:
+    ARCHWIZ_ROOT = Path(os.environ.get('ARCHWIZ_HOME', Path.home()))
+
+ARCHWIZ_DIR   = ARCHWIZ_ROOT / 'archwiz'
+DEEPCLI_DIR   = ARCHWIZ_ROOT / 'deepcli'
+SESSION_STORE = ARCHWIZ_ROOT / '.deepcli' / 'session_store'
+WORKSPACE_DIR = ARCHWIZ_ROOT / 'workspace'
+```
+
+All scripts import from `config.py` instead of constructing paths inline. `ARCHWIZ_ENV` overrides auto-detection for edge cases. This is portable across Termux, Replit, and local Linux without changing any call-site code.
+
+### 2. Silent Exception Swallowing in `core.py`
+`deepcli/deepcli/core.py:58-59` has a bare `except Exception: pass` around the ArchWiz dispatch call. If the dispatch pipeline fails (missing file, import error, broken path), the failure is completely invisible. The user sees normal operation while the pipeline is dead.
+
+```python
+# current (line ~55-59)
+try:
+    ...dispatch...
+except Exception:
+    pass   # ← silent failure, no log, no warning
+```
+
+**Fix:** At minimum log to stderr: `except Exception as e: print(f"[archwiz dispatch] {e}", file=sys.stderr, flush=True)`
+
+### 3. Duplicate Completion Paths (`send_message` vs `stream_completion`)
+`deepcli/deepcli/core.py` has two chat completion implementations. The methodology log (`archwiz/METHODOLOGY_INDEX.md`) confirms `send_message` had missing `thinking_enabled`/`search_enabled` fields causing "Update to latest version" API errors. The fix was applied but the two paths remain diverged — any future change to one may miss the other.
+
+**Fix:** Unify behind a single `_build_payload()` function. Both `send_message` and `stream_completion` call it. Remove the old `deepcli_old.py` and the backup `send_message_working` variant.
+
+### 4. Hardcoded Session ID Default
+`archwiz/archwiz.py:349` has a hardcoded session UUID as the fallback: `sid = '417ddd6d-9711-465d-ab90-c92cc04aeabf'`. This is a personal session ID that will silently target a non-existent session for any new user.
+
+**Fix:** Remove the hardcoded default. If no `.json` files exist in the session store, prompt the user to start a session first.
+
+### 5. Broken Symlinks at Root
+Multiple top-level symlinks are permanently broken on any non-Termux host:
+```
+dispatch_task.py → /data/data/com.termux/files/home/workspace/llm_map/dispatch_task.py
+agent_shell.py   → /data/data/com.termux/.../agent_shell.py
+archaeologist.py → /data/data/com.termux/.../archaeologist.py
+enforce_hierarchy.sh → /data/data/com.termux/.../enforce_workspace_hierarchy.sh
+```
+
+**Fix:** Either replace symlinks with relative path symlinks (pointing into `archwiz/` or `cli-synthegration/workspace/`) or remove them and update callers to use the canonical paths.
+
+### 6. No Dependency Declaration
+No `requirements.txt` exists. The Python environment depends on Termux `pkg` installs of: `curl_cffi`, `requests`, `ruff`, `ripgrep`, `fd`, `shellcheck`, `jq`, `entr`. On Replit, these must be installed explicitly.
+
+**Fix:** Create `requirements.txt` at the root with all Python deps. Add a `setup.sh` that installs system tools via `nix` or the package skill.
+
+---
+
+## Important Warnings
+
+### `.bak` File Pollution
+The `archwiz/` directory contains **~25 timestamped `.bak` files** for `archwiz.py` and `live_view.py` alone (`archwiz.py.bak.1782737822`, `archwiz.py.bak.$(date +%H%M%S)`, etc.). These:
+- Inflate repository size
+- Make `ls` and `rg` results noisy
+- One file is literally named `archwiz.py.bak.$(date +%H%M%S)` — the shell variable was never expanded
+
+**Recommendation:** Move all `.bak` files to a `_archive/` folder or delete them. Git history is the canonical backup mechanism.
+
+### commingle-swarm Is a Template / Scavenging Source
+`commingle-swarm/` is a **cloned/forked external repo** kept in the monorepo as a structural reference and code-scavenging template, not a first-class project to run or maintain. It is intentionally disconnected from the rest of the monorepo. Treat it as read-only reference material — do not install its dependencies, do not wire it into the pipeline, and do not include it in health checks or index sweeps.
+
+---
+
+## Optimization Proposals
+
+### A. Retire / Archive `export_poller.sh` and `activity_listener.py`
+These are legacy execution paths that predate the current `core.py` cache-write hook → `dispatch_pipeline.py` flow. They duplicate work the TUI already does and introduce a second, less-reliable execution surface. The methodology log documents the pain: 4 listener lifecycle attempts, nohup ghosts, PID-file fragility. The canonical path is: `core.py stream_completion()` writes cache → `dispatch_pipeline.update_all()` → `autonomous_runner`. The listener and poller should be archived (moved to `_archive/`) once the dispatch hook is confirmed stable on Replit.
+
+### B. `fzf` Integration (Shelved → Resolvable)
+CONSIDERATIONS.md documents why fzf was shelved: it indexed 194k files without respecting `bloat_exclusions.lst`. The fix is already documented:
+```bash
+find ~ -type d | grep -vFf bloat_exclusions.lst | fzf
+```
+The keyboard issue was Termux-specific and does not apply on Replit. This is ready to implement.
+
+### C. Real-Time Chat Feedback (ROADMAP Priority 🔴)
+The listener executes code blocks but cannot send results back to the conversation. The methodology log proves `stream_completion()` is the correct path (Attempt C). The missing piece is a `report_back(session_id, text)` helper that calls `stream_completion` with the execution result as a user message.
+
+### D. ChronoMancer Branch-Routing UI (ROADMAP 🟡)
+`cli-synthegration/Chronos/accelerator.py` and `versioner.py` have the data layer. What's missing is a TUI visualizer for the branch tree — a read-only `curses` (or rich-text) panel showing fork points and child session previews.
+
+### E. Self-Healing Sandbox (CONCEPT_INDEX: ❌ Not Built)
+The full loop: Sentinel detects a failure → auto-repair attempts a fix → Probe validates → promote if clean. `auto_repair.py` handles the Sentinel REVIEW tier. The gap is the detection→dispatch→promote chain being fully automated without human `[1]` invocation. This is ~50 lines of glue in `autonomous_runner.py`.
+
+### F. Web Dashboard (Replit-Native Extension)
+The cockpit is currently terminal-only (stdin/stdout). On Replit, a lightweight Flask/FastAPI server exposing the same 19 menu actions as REST endpoints, with a minimal HTML dashboard, would make the environment accessible from any browser — including mobile. The pipeline status, activity feed, and live metrics are natural candidates for this.
+
+### G. Expert-Mode Session Creation (ROADMAP 🟡)
+Sessions created without the `thinking_enabled`/`search_enabled` fields default to non-Expert mode. The `create_session()` call in `core.py` should accept and forward these flags, and `cli.py`'s `new` command should expose `--expert / --no-expert`.
+
+---
+
+## Extension Ideas
+
+| Idea | Effort | Value |
+|------|--------|-------|
+| Multi-account DeepSeek probing | Medium | Enables parallel task execution on account 2 |
+| Cross-session idea harvester | Medium | Scan all exports for novel `#concept` tags across sessions |
+| Prompt engine rotation (A/B test) | Low | Validate the CONSIDERATIONS.md prompt-phrase observations empirically |
+| Commit notes scanner → CHANGES.md | Low | Auto-detect "what changed" summaries from session digests |
+| Tab completion for `/sessions` | Low | Already partially designed in TUI |
+| Sigil substitution engine (cedrlang) | High | Runtime compression protocol — reduces token usage |
+
+---
+
+## User Preferences
+
+- Evaluate critically, propose optimizations and extensions
+- Preserve existing structure and stack — do not migrate or restructure
+- Check recent commits and branches before recommending changes

skills-lock.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "skills": {
+    "find-skills": {
+      "source": "vercel-labs/skills",
+      "sourceType": "github",
+      "skillPath": "skills/find-skills/SKILL.md",
+      "computedHash": "b146008599c31057cef1c145774cea5d5afb30e8f43fa802e47a4b461419aaaf"
+    }
+  }
+}