SeedPass/AGENTS.md

Repository Guidelines

Overstory Ecosystem

This project is part of the Overstory multi-agent development ecosystem. When asked to "update Overstory" or work on the ecosystem, these are the relevant repositories:

• Overstory — The coordinator. Orchestrates multi-agent workflows across worktrees.
• Mulch — Structured expertise/memory system for agents.
• Canopy — Prompt management system for agents.
• Seeds — Git-native issue tracker for agents.
• os-eco — The entire Overstory ecosystem (meta-repo/docs).

This project is written in Python. Follow these instructions when working with the code base.

Installation Quickstart for AI Agents

Prerequisites

Ensure the system has the required build tools and Python headers. Examples:

# Ubuntu/Debian
sudo apt update && sudo apt install -y \
    build-essential \
    libffi-dev \
    pkg-config \
    python3.11-dev \
    curl \
    git

# CentOS/RHEL
sudo yum install -y gcc gcc-c++ libffi-devel pkgconfig python3-devel curl git

# macOS
brew install [email protected] libffi pkg-config git

Installation

Run the installer script to fetch the latest release:

# Stable release
bash -c "$(curl -sSL https://raw.githubusercontent.com/PR0M3TH3AN/SeedPass/main/scripts/install.sh)"

# Beta branch
bash -c "$(curl -sSL https://raw.githubusercontent.com/PR0M3TH3AN/SeedPass/main/scripts/install.sh)" _ -b beta

Environment Layout

• Virtual environment: ~/.seedpass/app/venv/
• Entry point: ~/.seedpass/app/src/main.py

Verification

cd ~/.seedpass/app && source venv/bin/activate
cd src && python main.py --version  # Expected: SeedPass v[version]

Running SeedPass

cd ~/.seedpass/app && source venv/bin/activate
cd src && python main.py

Planning & Strategy

Before starting work, AI agents must consult the following documents to align with the current project trajectory:

1. Dev Control Center: The single source of truth for current priorities and "what to do next."
2. TUI v2 Execution Plan: The active roadmap for the TUI v2 mockup parity and hardening phase.

Project Expertise (Mulch)

This project uses Mulch for structured expertise management.

At the start of every session, run:

mulch prime

This injects project-specific conventions, patterns, decisions, and other learnings into your context. Use mulch prime --files src/foo.ts to load only records relevant to specific files.

Before completing your task, review your work for insights worth preserving — conventions discovered, patterns applied, failures encountered, or decisions made — and record them:

mulch record <domain> --type <convention|pattern|failure|decision|reference|guide> --description "..."

Link evidence when available: --evidence-commit <sha>, --evidence-bead <id>

Run mulch status to check domain health and entry counts. Run mulch --help for full usage. Mulch write commands use file locking and atomic writes — multiple agents can safely record to the same domain concurrently.

Before You Finish

1. Discover what to record:

   mulch learn
   

2. Store insights from this work session:

   mulch record <domain> --type <convention|pattern|failure|decision|reference|guide> --description "..."
   

3. Validate and commit:

   mulch sync
   

Issue Tracking (Seeds)

This project uses Seeds for git-native issue tracking.

At the start of every session, run:

sd prime

This injects session context: rules, command reference, and workflows.

Quick reference:

• sd ready — Find unblocked work
• sd create --title "..." --type task --priority 2 — Create issue
• sd update <id> --status in_progress — Claim work
• sd close <id> — Complete work
• sd sync — Sync with git (run before pushing)

Before You Finish

1. Close completed issues: sd close <id>
2. File issues for remaining work: sd create --title "..."
3. Sync and push: sd sync && git push

Prompt Management (Canopy)

This project uses Canopy for git-native prompt management.

At the start of every session, run:

cn prime

This injects prompt workflow context: commands, conventions, and common workflows.

Quick reference:

• cn list — List all prompts
• cn render <name> — View rendered prompt (resolves inheritance)
• cn emit --all — Render prompts to files
• cn update <name> — Update a prompt (creates new version)
• cn sync — Stage and commit .canopy/ changes

Do not manually edit emitted files. Use cn update to modify prompts, then cn emit to regenerate.

Running Tests

SeedPass maintains a comprehensive test infrastructure. Agents should use the central inventory as a guide:

1. Test Infrastructure Inventory: A complete index of all unit, integration, UI, and determinism tests.

Quick Start: Running Tests

1. Set up a virtual environment and install dependencies: ...

   pytest
   

   For a full CI-equivalent run (highly recommended before any PR), use:

   bash scripts/run_ci_tests.sh
   

Local CI: the two gates that matter

TypeScript is the implementation going forward; Python is the reference it is validated against. Both are covered by two gates, and they have meanings, not just names:

./scripts/ci_prepush.sh    # ~45s. Run before every push.
./scripts/ci_parity.sh     # minutes. Run before calling a branch ready.

An agent may not report a task complete or push until ci_prepush.sh passes, and may not call a branch merge-ready until ci_parity.sh passes.

Both begin with scripts/ci_preflight.py, which verifies this machine agrees with the lockfiles and refuses to continue when it does not. That is not ceremony. On 2026-08-20 the local environment held black 26.1.0 while poetry.lock pinned 24.10.0, so poetry run black --check . passed locally and failed on GitHub — and an earlier commit titled "satisfy the black gate" had already reformatted five files with the wrong black, making CI worse while looking like a fix. A local gate that disagrees with CI is worse than no gate, because people stop reading the real result.

If preflight fails, repair with:

./scripts/dev_sync.sh      # the only script that mutates your environment

Two rules follow from this and apply to everything you write here:

• Invoke tools through the repository, never off PATH. poetry run black, pnpm -C js lint — never a bare black or oxlint. A bare name is exactly how a local run and a CI run end up disagreeing about the same source.
• Never add a check that cannot fail. Two shipped examples were found and removed on 2026-08-20: a test step whose failures pwsh discarded on Windows, and an SBOM step that swallowed its own error and uploaded nothing. A green check nobody can turn red is worse than an absent one, because it is trusted.

Enable the pre-push hook once per clone:

git config core.hooksPath .githooks

Currently the test folder is located in src/tests/. New tests should be placed there so pytest can discover them automatically.

Style Guidelines

• Adhere to PEP 8 conventions (4‑space indentation, descriptive names, docstrings).

• Use black to format Python files before committing:

  black .
  

• Optionally run flake8 or another linter to catch style issues.

Security Practices

• Never commit seed phrases, passwords, private keys, or other sensitive data.
• Use environment variables or local configuration files (ignored by Git) for secrets.
• Review code for potential information leaks (e.g., verbose logging) before submitting.

Following these practices helps keep the code base consistent and secure.

Deterministic Artifact Generation

• All generated artifacts (passwords, keys, TOTP secrets, etc.) must be fully deterministic across runs and platforms.
• Randomness is only permitted for security primitives (e.g., encryption nonces, in-memory keys) and must never influence derived artifacts.

Legacy Index Migration

• Always provide a migration path for index archives and import/export routines.
• Support older SeedPass versions whose indexes lacked salts or password-based encryption by detecting legacy formats and upgrading them to the current schema.
• Ensure migrations unlock older account indexes and allow Nostr synchronization.
• Add regression tests covering these migrations whenever the index format or encryption changes.

Integrating New Entry Types

SeedPass supports multiple kind values in its JSON entry files. When adding a new kind (for example, SSH keys or BIP‑39 seeds) use the checklist below:

1. Menu Updates – Extend the CLI menus in main.py so "Add Entry" offers choices for the new types and retrieval operations handle them properly. The current main menu looks like this:

   Select an option:
   1. Add Entry
   2. Retrieve Entry
   3. Search Entries
   4. Modify an Existing Entry
   5. 2FA Codes
   6. Settings
   7. Exit
   

2. JSON Schema – Each entry file must include a kind field describing the entry type. Add new values (ssh, seed, etc.) as needed and implement handlers so older kinds continue to work.

3. Best Practices – When introducing a new kind, follow the modular architecture guidelines from docs/entry_types.md:

   • Use clear, descriptive names.
   • Keep handler code for each kind separate.
   • Validate required fields and gracefully handle missing data.
   • Add regression tests to ensure backward compatibility.

This procedure keeps the UI consistent and ensures new data types integrate smoothly with existing functionality.

Repo memory

Curated agent memory lives in .agents/ (index: .agents/MEMORY.md). Read it before substantive work. Propose additions as files in .agents/proposals/; trusted memory under .agents/memory/ changes only through reviewed commits. Code, tests, and configuration always outrank memory.