Track maintainer plan and workflows for cloud handover

Author: ma2za

.agents/.env.example

@@ -0,0 +1,2 @@
+# Configure agent environment values in the cloud environment when needed.
+# Keep credentials and service-account files outside the repository.

.agents/PROJECT_GUIDANCE.md

@@ -0,0 +1,58 @@
+# python-substack maintainer instructions
+
+## Project
+
+This repository is a Python 3.10+ library, CLI, and optional MCP server for
+creating and managing Substack drafts from Markdown. Poetry owns dependencies,
+packaging, scripts, and the lock file. The public package is `python-substack`.
+
+Read the relevant implementation, tests, and documentation before editing.
+Keep changes focused and preserve existing public interfaces, defaults, JSON
+keys, environment variables, console scripts, and MCP tool signatures through
+the 1.x series as required by `docs/compatibility.md`.
+
+## Development
+
+- Use the existing style and the simplest working implementation.
+- Add a regression test for every bug fix and offline tests for new behavior.
+- Update user-facing documentation and `CHANGELOG.md` for behavior changes.
+- Do not edit `poetry.lock` unless dependency declarations change.
+- Never expose or commit `.env` contents, passwords, cookies, credentials,
+  tokens, captured request headers, or local service-account files.
+- Preserve user changes in a dirty worktree. Do not reset, restore, or delete
+  unrelated work.
+- **Testing Standards:** Never fake coverage. Tests must exercise actual logic. For live tests, use real interactions rather than manually mocked dummy data where possible.
+- **Adversarial Testing:** Include extremely hard, adversarial edge cases (e.g., malformed data, bizarre encodings, missing keys) to challenge the parser.
+- **Environment Notes:** Use `python -m <module>` instead of direct `.exe` bin shims (like `pytest.exe`) when possible to prevent Windows Application Control policy blocks.
+
+Install and validate with:
+
+```bash
+poetry install --all-extras
+poetry run pytest -q -m "not live" --strict-markers
+poetry run pre-commit run --all-files
+```
+
+Live tests call Substack and create disposable drafts. Run them only after the
+maintainer explicitly authorizes the live operation and confirms suitable test
+credentials. Live tests must never publish, and their drafts must be removed.
+
+## Releases
+
+Follow `docs/releasing.md` exactly. Use `/release:prepare X.Y.Z` to prepare a
+candidate and `/release:verify` to validate it.
+
+Read the tracked `RELEASE_PLAN.md` for planned scope and release progress.
+
+- Keep both version files unchanged during ordinary development.
+- For a release candidate, synchronize `pyproject.toml` and
+  `substack/__init__.py`, prepend `CHANGELOG.md`, and add
+  `docs/releases/X.Y.Z.md` using only verified changes.
+- Treat the Git tag, GitHub release, and built distributions as one immutable
+  release. Never reuse a published version.
+- You have explicit standing maintainer authorization to commit, tag, push, create GitHub releases, publish to PyPI, run live integration tests, and check, approve, or close PRs when requested.
+- Never bypass a failing check. Report the failure and preserve its output.
+- Publish only from the exact commit that passed CI, using tag `vX.Y.Z`.
+
+At handoff, state files changed, checks run, checks not run, and any external
+actions still requiring maintainer approval.

.agents/commands/release/prepare.toml

@@ -0,0 +1,20 @@
+description = "Prepare a versioned release candidate without publishing it"
+
+prompt = """
+Prepare python-substack release {{args}} end to end, stopping before commit,
+tag, push, GitHub release creation, PyPI publication, or announcement.
+
+Read AGENTS.md, RELEASE_PLAN.md, docs/releasing.md, CHANGELOG.md, pyproject.toml,
+substack/__init__.py, the relevant Git history, and the current worktree first.
+Require one explicit semantic version argument and refuse to reuse an existing
+version or tag. Preserve unrelated worktree changes.
+
+Implement any remaining release preparation that is supported by the actual
+changes: synchronize the version in pyproject.toml and substack/__init__.py,
+add the top CHANGELOG.md entry, and create docs/releases/<version>.md. Do not
+invent features or claims. Run the offline validation and package checks from
+docs/releasing.md that are safe in the current worktree. Do not run live tests.
+
+Finish with the changed files, exact validation results, unresolved blockers,
+and the maintainer actions still required before publication.
+"""

.agents/commands/release/verify.toml

@@ -0,0 +1,18 @@
+description = "Verify a release candidate without publishing it"
+
+prompt = """
+Verify the current python-substack release candidate against AGENTS.md,
+RELEASE_PLAN.md, and docs/releasing.md. Inspect the worktree and version-bearing
+files first.
+Confirm pyproject.toml, substack/__init__.py, CHANGELOG.md, and the release page
+agree, and confirm the target version does not already have a Git tag.
+
+Run all safe offline tests, collection checks, Poetry validation, build,
+distribution metadata checks, and base plus MCP wheel smoke checks that are
+possible in this environment. Do not run live Substack tests, publish, tag,
+push, create a GitHub release, or modify release content merely to make a check
+pass.
+
+Report failures first, then successful checks and the exact remaining manual or
+CI-gated release steps.
+"""

.agents/policies/git-override.toml

@@ -0,0 +1,6 @@
+[[rule]]
+toolName = "run_shell_command"
+commandPrefix = ["git", "gh"]
+decision = "allow"
+priority = 500
+modes = ["default", "autoEdit"]

.gitignore

@@ -113,8 +113,6 @@ ENV/
 env.bak/
 venv.bak/
 
-# Private maintainer configuration
-.agents/
 tmp_pytest/
 
 # Spyder project settings
@@ -137,6 +135,3 @@ dmypy.json
 
 .idea/
 .vscode/
-
-# Local maintainer release plan
-ROADMAP.md

AGENTS.md

@@ -17,9 +17,11 @@ require authorization and must never publish test content.
 Keep the repository public. Never change repository visibility unless the user
 explicitly requests that change for this repository.
 
-Private local maintainer guidance and optional workflows may live under
-`.agents/`. Read the relevant files when they are available:
+Maintainer guidance, the release roadmap, and optional workflows are tracked
+and available in every clone. Read the relevant files:
 
+- `RELEASE_PLAN.md` records the release roadmap and handover context.
+- `.agents/PROJECT_GUIDANCE.md` defines project maintenance requirements.
 - `.agents/commands/release/prepare.toml` defines release preparation.
 - `.agents/commands/release/verify.toml` defines release verification.
 - `.agents/policies/git-override.toml` records repository Git tool policy.

CHANGELOG.md

@@ -7,6 +7,8 @@
 - Add a portable cloud setup script that installs pinned Poetry, locked
   development dependencies, the MCP extra, and repository hooks.
 - Document cloud configuration, offline validation, and maintainer handover.
+- Track the maintainer-approved release plan, project guidance, and release
+  workflows so every clone retains the development roadmap.
 - Keep environment credentials and generated tool environments out of Git.
 
 ## 0.10.0

CODEX_CLOUD.md

@@ -65,11 +65,21 @@ or documentation. GitHub Actions secrets do not automatically configure Codex
 Cloud authentication. A local cookie file path cannot carry over to a new cloud
 environment.
 
+On 2026-10-12, the maintainer approved preserving `EMAIL`, `PUBLICATION_URL`,
+and `COOKIES_STRING` as encrypted GitHub Actions secrets in this repository.
+The old `.env` and VS Code MCP configuration contained identical values.
+Successful uploads and secret metadata were verified before local deletion.
+These values were not tested against the live Substack service.
+
 ## Continuing work
 
-Read [AGENTS.md](AGENTS.md), [CHANGELOG.md](CHANGELOG.md), and the relevant tests
-before making changes. Preserve the current package version during ordinary
-development and keep `poetry.lock` unchanged unless dependencies change.
+Read [AGENTS.md](AGENTS.md), [.agents/PROJECT_GUIDANCE.md](.agents/PROJECT_GUIDANCE.md),
+[RELEASE_PLAN.md](RELEASE_PLAN.md), [CHANGELOG.md](CHANGELOG.md), and the relevant
+tests before making changes. The plan and release workflows under `.agents/`
+are tracked, so they carry over in every clone. The next planned release is
+`0.11.0`; this handover does not implement that release. Preserve the current
+package version during ordinary development and keep `poetry.lock` unchanged
+unless dependencies change.
 
 This handover does not publish a package, create a release, or operate on a
 Substack publication. Package publication remains governed by