Skip to content

AGENTS.MD

Latest commit

 

History

History
172 lines (130 loc) · 6.03 KB

AGENTS.MD

File metadata and controls

172 lines (130 loc) · 6.03 KB
Raw

AI Constitution for PageSeeds CLI

Primary guide for AI agents working on the PageSeeds CLI project.

Purpose

PageSeeds CLI is an open-source automation toolkit for:

  • SEO research and content operations
  • Reddit opportunity search and engagement workflows
  • Deterministic utility automations with agent-assisted workflows

Design goal: Provide a complete, installable tool (pageseeds) that users can install via uv/pip and use to manage their website automation workflows.

Architecture Snapshot

pageseeds-cli/
├── packages/
│   ├── automation-cli/     → Core automation commands (reddit, gsc, posthog)
│   ├── seo-cli/            → SEO research tools (ahrefs, keywords)
│   └── seo-content-cli/    → Content lifecycle operations
├── dashboard_ptk/          → Interactive TUI + orchestration engine
└── .github/skills/         → Workflow knowledge source of truth

Command entry point: pageseeds (unified CLI)

Execution context: Target repos under .github/automation/

User Installation

Users install PageSeeds CLI in their workspace:

# Using uv (recommended)
uv tool install git+https://github.com/fstrauf/pageseeds-cli

# Or using pip
pip install git+https://github.com/fstrauf/pageseeds-cli

Then configure in their target website repos:

cd /path/to/website
git init  # if not already a git repo
pageseeds automation repo init --site-id my-site

Two-Agent Operating Model

Use this model whenever two agents collaborate on work in this repo.

Agent A: Planner/Architect

Responsibilities:

  • Clarify objective, constraints, acceptance criteria
  • Define interfaces and boundaries before edits
  • Identify migration and rollback implications
  • Produce decision-complete change plan

Must deliver:

  • scope
  • affected files/modules
  • invariants to preserve
  • test/verification plan

Agent B: Implementer

Responsibilities:

  • Execute against the plan
  • Keep changes minimal and cohesive
  • Preserve backward compatibility unless explicitly changing schema/contracts
  • Validate behavior with tests/checks

Must deliver:

  • working code
  • updated docs
  • verification results
  • known limitations

Handoff Contract

Before coding handoff, Agent A provides:

  1. exact modules to create/modify
  2. expected data contracts
  3. success/failure behavior
  4. test scenarios

After implementation handoff, Agent B provides:

  1. what changed
  2. what was verified
  3. residual risks

Core Rules

  1. Skills are source of truth.

    • Workflow logic belongs in .github/skills/*/SKILL.md.
    • Prompts are launchers, not full workflow specs.

  2. Never push or commit on behalf of the user.

    • Do NOT run git push, git commit, git add, git checkout -b, or any command that creates branches, commits, or pushes to a remote.
    • File edits are made to the working tree only. The user commits and deploys when ready.

  3. Deterministic steps use CLIs.

    • Prefer explicit pageseeds automation seo ..., pageseeds reddit ... calls.
    • Avoid shell parsing pipelines for core logic.

  4. Agentic steps must be observable.

    • Persist raw agent output artifacts.
    • Normalize to structured artifacts deterministically.

  5. Secrets stay machine-local.

    • Use env vars or ~/.config/pageseeds/secrets.env.
    • Never embed keys in repo files.

  6. No mock data unless explicitly requested.

  7. One content-dir resolver.

    • Use dashboard_ptk/dashboard/engine/content_locator.py for content directory discovery.
    • Do not reimplement candidate path scans in UI/runners/utils.
    • Project content_dir override must take precedence when valid.

  8. No direct subprocess outside engine.

    • subprocess.run is only allowed in dashboard_ptk/dashboard/engine/*.
    • UI (dashboard/cli.py) and task runners must call engine services/tool registry instead.

  9. Date edits must be frontmatter-safe.

    • For markdown date fixes, update YAML frontmatter deterministically first, then sync task metadata/JSON.
    • Do not use broad regex replacements that can modify body content.

Where to Change Things

  • Dashboard orchestration: dashboard_ptk/dashboard/engine/
  • Dashboard UI shell: dashboard_ptk/dashboard/cli.py, dashboard_ptk/dashboard/batch.py
  • Task runners: dashboard_ptk/dashboard/tasks/
  • Task persistence/schema migration: dashboard_ptk/dashboard/storage/, dashboard_ptk/dashboard/engine/task_store.py, dashboard_ptk/dashboard/engine/migration.py
  • CLI implementations: packages/*/src/
  • Workflow knowledge: .github/skills/

Adding Functionality (Standard Path)

  1. Define capability and acceptance criteria.
  2. Decide deterministic vs agentic split.
  3. Add/extend deterministic CLI command first (if needed).
  4. Wire orchestration in dashboard engine workflows.
  5. Add/update task schema mappings only when required.
  6. Add tests for:
    • migration/compatibility (if schema touched)
    • deterministic execution path
    • normalization behavior (if agent output used)
  7. Update docs in place (AGENTS.MD, ARCHITECTURE.md, dashboard guide).

Changing Existing Behavior Safely

  1. Preserve task state compatibility by default.
  2. If schema changes, provide migration + backup + rollback behavior.
  3. Keep UI behavior stable unless change is intentional.
  4. Do not introduce parallel/duplicate runtime paths.
    • one canonical execution path through dashboard/engine
  5. If project setup/validation behavior changes, update preflight checks and interactive fix paths together.

Pre-Commit Checklist

  • No secrets added
  • No hardcoded absolute machine paths in runtime logic
  • Deterministic calls go through centralized tool execution
  • Agent outputs are persisted and normalized when structured results are required
  • Docs updated in existing files (no duplicate guidance)
  • Tests executed and reported
  • test_no_subprocess_outside_engine.py passes
  • If content directory logic changed: test_content_locator.py and test_project_preflight.py updated/passing
  • If date-fix logic changed: test_frontmatter_dates.py (and affected workflow tests) updated/passing