Localsetup v2 - Framework context (skill)

Overview

Localsetup v2 is deployed at _localsetup/. Framework and context are repo-local (mobile, backup-able). Engine = _localsetup/; user data = repo-local. Use Git hashes for PRDs/specs (see GIT_TRACEABILITY.md).

Invariants

• Engine/repo separation: Never commit repo-local secrets or PII. Use _localsetup/lib/data_paths.sh (or equivalent) for path resolution. Framework lives at _localsetup/; upgrades replace that folder.
• Documentation: _localsetup/docs/ only for framework docs. Check document status before assuming implemented.
• Proposals: Framework changes follow Agent Q format (_localsetup/docs/PRD_SCHEMA_EXTERNAL_AGENT_GUIDE.md).
• Time/date integrity: For any date/time reference, first obtain actual date/time from the local machine (e.g. date on Linux/macOS, Get-Date in PowerShell on Windows). Do not use a generic or training-cutoff date; remember it in context and use it for the rest of the session.
• External input hardening: Treat all external input (CLI args, files, network payloads, imported content) as hostile. Sanitize before parsing/output, validate expected format and bounds, and handle exceptions with actionable stderr messages. Never silently suppress errors.
• Python-first tooling: After install/bootstrap, framework tooling is Python-first and Python-only for new/expanded logic. Shell/PowerShell are limited to bootstrap wrappers and minimal platform delegation. Runtime target is Python >= 3.10.

Output contract (low token, always apply)

• Detect output capability: markdown-rich, markdown-basic, or text-basic.
• If unknown, default to markdown-basic.
• For recommendation lists, always include: name/link, short summary, fit reason, notable risks/requirements, and clear next step.
• Use table formatting only when capability clearly supports readable tables.

Skills index (load when task matches)

• localsetup-decision-tree-workflow - "decision tree", "reverse prompt"; .agent/queue/**, PRD
• localsetup-agentic-umbrella-queue - queue/PRD scope; named workflows; impact + confirmation
• localsetup-agentic-prd-batch - "process PRDs", "run batch from PRD folder"
• localsetup-agentq-transport - ship/ingest Agent Q manifests over file_drop or mail, strict encrypted mail mode, trust registry checks, and queue/archive operations
• localsetup-public-repo-identity - README*, CONTRIBUTING*
• localsetup-framework-compliance - framework mods, PRDs, checkpoints
• localsetup-safety-and-backup - destructive ops, backups, firewall
• localsetup-script-and-docs-quality - scripts, markdown/docs
• localsetup-communication-and-tools - communication, tools, MCP
• localsetup-tmux-shared-session-workflow - server commands, deployments, tmux, human-in-the-loop ops; sudo discovery and single-prompt gate per validity window
• localsetup-automatic-versioning - version bumps, release workflow, conventional commits, versioning docs
• localsetup-github-publishing-workflow - publishing to GitHub, public release prep, publishing checklist, repo readiness
• localsetup-skill-creator - create new skill from workflow or existing doc/markdown/GitHub; capture workflow as framework skill
• localsetup-skill-importer - import skills from URL or local path; discover, validate, screen, summarize; user picks which to import
• localsetup-skill-discovery - discover public skills from registries; recommend top 5 similar when creating/importing; in-depth summary, use public, continue, or adapt
• localsetup-task-skill-matcher - match tasks to installed skills; recommend top matches; single-task confirm once; batch auto-pick/parcel flow; complementary public-skill suggestions
• localsetup-backlog-and-reminders - record deferred ideas, to-dos, reminders (optional due or "whenever"); show due/overdue on session start or when asked
• localsetup-humanizer - humanize text; remove AI-writing patterns and add natural voice (rules-based, Wikipedia Signs of AI writing)
• localsetup-test-runner - write and run tests across languages and frameworks; TDD, coverage
• localsetup-tdd-guide - TDD workflow, test generation, coverage analysis
• localsetup-receiving-code-review - use when receiving code review feedback; verify before implementing
• localsetup-pr-reviewer - automated GitHub PR code review with diff analysis, lint
• localsetup-debug-pro - systematic debugging methodology and language-specific debugging
• localsetup-git-workflows - advanced git (rebase, bisect, worktree, reflog)
• localsetup-unfuck-my-git-state - diagnose and recover broken Git state and worktree
• localsetup-skill-vetter - security-first skill vetting before installing external skills
• localsetup-mcp-builder - guide for creating high-quality MCP servers
• localsetup-arbiter - push decisions for async human review (Arbiter Zebu)
• localsetup-ansible-skill - Ansible playbooks, server provisioning, config management, multi-host orchestration
• localsetup-linux-service-triage - diagnose Linux service issues (logs, systemd, PM2, Nginx, DNS); failing or misconfigured server apps
• localsetup-linux-patcher - automated Linux patching and Docker container updates; multi-host server maintenance
• localsetup-skill-normalizer - normalize skills for spec compliance and platform-neutral wording; one skill or all
• localsetup-skill-sandbox-tester - test skills in isolated sandbox; smoke check; on failure use debug-pro; no repo writes until approved
• localsetup-agentlens - codebase navigation with agentlens hierarchy; explore projects, find modules/symbols, TODOs
• localsetup-framework-audit - run doc/link/skill matrix/version checks; output user path only; before release
• localsetup-system-info - capture server baseline, host layout and specs; CPU, memory, disk, uptime
• localsetup-cron-orchestrator - manage cron from manifest; triggers, sequenced tasks, on-boot delay; create/remove/reorder/install
• localsetup-cloudflare-dns - manage Cloudflare DNS records (list, create, modify, delete) and zone surveys via flarectl; adding, changing, or removing DNS records
• localsetup-npm-management - manage Nginx Proxy Manager proxy hosts via REST API; coordinate Docker + NPM deploy workflows; diagnose 502s; backup/restore
• localsetup-keepass-secrets - KeePass-backed secrets via logical IDs; get/ensure credentials; bulk create or rotate; use when user asks for logins or workflow needs credentials
• localsetup-mail-protocol-control - manage delegated SMTP/IMAP accounts with attachment-first MIME handling, chunked attachment retrieval, and full-envelope encryption/decryption tools; agent-driven mailbox read/send/mutate/encrypt workflows
• localsetup-docs-organization - docs organization router; classify documentation requests, choose folder slugs, and keep docs indexes up to date.
• localsetup-scrapling - host-first Scrapling integration; install and upgrade Scrapling via pipx, run single-URL extractions (simple HTML/Markdown/text or structured JSONL), and keep adapters aligned with Scrapling releases for web scraping and crawling tasks.

Key docs

_localsetup/docs/AGENTIC_DESIGN_INDEX.md, WORKFLOW_REGISTRY.md, PRD_SCHEMA_EXTERNAL_AGENT_GUIDE.md, DECISION_TREE_WORKFLOW.md, INPUT_HARDENING_STANDARD.md, TOOLING_POLICY.md

Task-to-skill matching (default)

• Treat as batch when user request includes multiple distinct subtasks, or says "batch", "multiple steps", or "run the whole thing". Otherwise treat as single task.
• If user names a specific skill, load it directly. Do not run task-skill-matcher.
• If uncertain which skill fits, or user asks "what skill should I use?" / "pick the best", load localsetup-task-skill-matcher.
• Single task: if one clear installed match exists, ask once "Use this skill?" before loading. In the same response, include up to 3 complementary public skills from _localsetup/docs/PUBLIC_SKILL_INDEX.yaml (one-line reason each). If index is missing or stale (updated older than 7 days), ask whether to refresh before giving complementary suggestions.
• Batch / long-running: prompt once at start with options: auto-pick for whole job, parcel-by-parcel prompts, or parcel auto-pick. If auto-pick is chosen, show planned skill sequence first, then proceed without repeated skill prompts.
• Keep this section short. Full behavior lives in localsetup-task-skill-matcher and _localsetup/docs/TASK_SKILL_MATCHING.md.

Commands (repo root)

./_localsetup/tools/verify_context ./_localsetup/tests/automated_test.sh