vh
0 Followers · 0 Following
  • Joined on 2024-05-22
Repositories
29
 Projects Packages Public Activity Starred Repositories
1

albok (0.1.0)

Published 2026-10-02 08:13:01 -07:00 by vh

Installation

pip install --index-url https://gitea.phasefinal.com/api/packages/vh/pypi/simple/ --extra-index-url https://pypi.org/simple albok

About this package

Albok — the fleet knowledgebase engine: the LLM-free knowledge store and retrieval package, plus the service that owns the store. Extracted from Worldtree (#412 follow-on; design record in docs/design/albok/).

Corviduo project template

Canonical scaffold for new Corviduo projects. Captures the conventions that recur across Worldtree, Skaldsong, vastai-app (Vast Blue SEA), sleipnir, Vor, Galdrabok, task-board, althing, and any future sibling. When a new Corviduo project lands, copy this scaffold in rather than re-deriving the shape from Worldtree by hand.

What this template provides

Path Purpose
CLAUDE.md Top-level Claude Code conventions (Think Before Coding · Simplicity First · Surgical Changes · Goal-Driven Execution + Corviduo conventions: contracts-first · no-backwards-compat-until-v1.x · persistent-memory + housekeeping commit-along · TDD cycle · Sleipnir AFK hygiene · task-board reporting). Project-name placeholder uses albok — search-and-replace after copy.
PRINCIPLES.md The four Corviduo engineering principles (Excellence over uniqueness · Explicit over implicit · Elegance is a byproduct · Action-relevance over thoroughness). Canonical — copied as-is.
persistent-memory.md Durable intent across context resets — skeleton with the four canonical sections (Repo purpose / Current state / Recent decisions / Tried and abandoned). Project-agnostic.
ROADMAP.md Anti-creep roadmap skeleton — v1 target (3–7 capabilities) + parking lot + the feature-gate (default = parking lot) + creep-check. albok placeholder; content diverges per project (a skeleton like persistent-memory.md, not a byte-canonical). The discipline lives in user-global CLAUDE.md § "Roadmap discipline"; this file is its per-project instance.
README.md Project README skeleton; albok placeholder.
docs/architecture.md Top-level module map placeholder; project-agnostic structure.
docs/methodology.md The Corviduo preferred development pipeline ((optional) Vor → (required) Contract → branch (direct or AFK TDD) → verify → merge/commit). Generic — copied as-is.
docs/canonical-sync.md The canonical-sync pattern, mechanism (.<project>-canonicals.toml manifest + canonical_sync.py + canonical_drift.py), publisher / consumer adoption steps, v→v<N+1> bump procedure, and documented adopters table (current: Worldtree, Galdrabok, Bifrost). Read when a project ships a canonical spec or pins against one.
docs/CODEBASE-CONVENTION.md Convention for docs/CODEBASE.md navigation maps (v0.1, experimental, recommended-only). Adopt via canonical-sync pin when a project is large enough to warrant a map.
docs/VERSIONING-POLICY.md Versioning policy for all projects — SemVer 2.0.0, the public-contract declaration, pre-release staging, dev labeling, release process. Copied as-is.
docs/codex-dispatch-protocol.md Canonical schema for the codex-dispatch message + the handshake-v1 write-window protocol. Adopters point here rather than re-declaring.
docs/intent-line.md The ⟦INTENT⟧ / ⟦STATE⟧ / ⟦DECIDE⟧ marker convention + opt-in UserPromptSubmit hook (Ledger-legible per-session Goal / State / pending-decision signals).
docs/althing-monitoring.md Inbound convention for interactive sessions: althing 2.0.0 herald + wake-listener (default), self-poll monitor (fallback). Mechanism lives in the althing repo.
docs/contracts/CONTRACT-FORMAT.md The canonical contract spec (v2.1). Generic infrastructure — copied as-is.
docs/contracts/contract_parser.py Validates and extracts structured fields from .contract.md files. Generic — copied as-is.
docs/contracts/issues/ Empty directory for issue-scoped contracts (<N>.contract.md shape).
scripts/contract_drift_check.py Verifies issue-scoped contracts' prd: block hashes match the live tracker state. Generic — copied as-is.
scripts/canonical_sync.py Operator-triggered canonical re-sync: fetches each pinned canonical from its source, writes the consumer copy, bumps the pin's hash + timestamp.
scripts/canonical_drift.py Read-only drift verifier (CI-gating): flags any pin stale against its source or diverged from the pinned hash. Exits non-zero on drift.
.sleipnir/config.yaml.template Sleipnir per-project config. cp to .sleipnir/config.yaml (gitignored) and edit.
env.sh.template Environment variables template. cp to env.sh (gitignored) and fill in.
.gitignore Python-project standards (uv/poetry/pdm/pip caches; Sleipnir per-project config; logs; data; venv; ruff/mypy caches; IDE; OS).
.corviduo-canonicals.toml Self-pin manifest declaring the canonicals this repo owns + their pinned hashes; drives canonical_sync.py / canonical_drift.py.
tests/ Empty directory for the test suite.
LICENSE Canonical proprietary license (all rights reserved). Copied as-is into new projects — Corviduo work is private; this LICENSE makes intent explicit at the repo level rather than relying on the legal "all rights reserved" default.

What this template does NOT provide

  • Project-specific module structure (per-module core/<name>/CLAUDE.md files, etc.)
  • Project-specific runtime (no core/ package; no agents directory; no transports)
  • An issue tracker adapter (core.issues is Worldtree-specific; build per-project as needed)
  • A specific dependency manager — pick uv / poetry / pdm / bare pip and add the appropriate manifest after copy
  • Project-specific Sleipnir config (the template ships a config.yaml.template; rename + edit per checkout)
  • A specific LLM provider (the env.sh template enumerates options, none are mandatory)

How to use

# 1. Copy the template into a new project location
PROJECT_NAME=myproject
cp -r /home/lkraven/development/corviduo-project-template "$HOME/development/$PROJECT_NAME"
cd "$HOME/development/$PROJECT_NAME"

# 2. Replace the albok placeholder
find . -type f \( -name '*.md' -o -name '*.yaml' -o -name '*.template' \) \
     -not -path './.git/*' -not -path './docs/contracts/CONTRACT-FORMAT.md' \
     -exec sed -i "s/albok/$PROJECT_NAME/g" {} +

# 3. Reset git history for this project
rm -rf .git
git init -q
git add -A
git commit -m "init: seed from corviduo-project-template"

# 4. Set up local environment
cp env.sh.template env.sh
$EDITOR env.sh                 # fill in values
cp .sleipnir/config.yaml.template .sleipnir/config.yaml
$EDITOR .sleipnir/config.yaml  # adjust per-project (gitignored)
python -m venv .venv
source .venv/bin/activate
source env.sh

# 5. Author the project-specific README + persistent-memory + architecture
$EDITOR README.md
$EDITOR persistent-memory.md
$EDITOR docs/architecture.md

# 6. (Optional) register with Gitea, add a remote, then push
git remote add origin "git@gitea.phasefinal.com:vh/$PROJECT_NAME.git"
git push -u origin main

Maintenance

When the convention shifts in one Corviduo project (Worldtree usually leads on tooling changes — Sleipnir hygiene, contract format, drift checker), the canonical template is the place to backport. Workflow:

  1. Identify the Worldtree commit that established the new convention.
  2. Apply the equivalent change here.
  3. Bump the template's version note in CLAUDE.md change-log section if the change is non-cosmetic.
  4. Existing project copies are not auto-synced — operators pull selectively via git diff against the template path.

Versioning

The template doesn't carry its own semver. The four load-bearing pieces (CLAUDE.md, CONTRACT-FORMAT.md, contract_parser.py, contract_drift_check.py) each have their own internal versioning where applicable. Pin the contract format version in each project's frontmatter (contract_version: "2.1").

Sibling Corviduo projects (reference)

  • Worldtree — multi-agent framework (the canonical source)
  • Skaldsong — story-generation engine
  • Vast Blue SEA — multi-agent web app
  • Sleipnir — AFK orchestrator
  • Vor — pre-contract design partner UI
  • Galdrabok — Sleipnir-preflight skill author
  • task-board — per-session web UI
  • althing — newest, seeded from this template 2026-05-07

Requirements

Requires Python: >=3.11
Details
PyPI
2026-10-02 08:13:01 -07:00
6
Vuong Hoang
Proprietary
547 KiB
Assets (2)
albok-0.1.0-py3-none-any.whl 86 KiB
albok-0.1.0.tar.gz 460 KiB
Versions (9) View all
1.0.0a1 2026-10-16
0.1.12 2026-10-16
0.1.11 2026-10-16
0.1.10 2026-10-12
0.1.4 2026-10-04