vibefree 0.2.1

A tiny CLI initializer for vibe coding projects that generates .memory and .harness scaffolding.

vibefree 🚀

vibefree 是一个轻量级 vibe coding 项目初始化工具，用于生成 .memory 和 .harness 上下文结构。

它的目标是帮助开发者在使用 opencode / coding agent / AI coding workflow 时，快速建立项目记忆、开发规则、架构上下文和任务交接入口。

GitHub: https://github.com/lemonmindyes/vibefree

作者: lemonmindyes

✨ 功能特性

• 一键生成 .memory
• 一键生成 .harness
• 默认不覆盖已有文件
• 支持 --force 重置受管 .memory 文件
• 适合 opencode / coding agent 工作流
• 轻量、可读、可手动维护
• 支持当前目录初始化
• 支持创建新项目目录并初始化

📦 安装

从 PyPI 安装：

pip install vibefree

⚡ 使用

在当前目录初始化：

vibefree init

创建并初始化一个新项目目录：

vibefree init my-project

如果 my-project 不存在，vibefree 会创建它；如果已存在，则会在其中补齐缺失的上下文文件。

已有文件不会被覆盖，适合在项目演进过程中重复运行。

如需重置受管 .memory 文件为默认模板：

vibefree init --force

重复运行 init 会清理 .memory 下非目标结构并补齐缺失文件；默认不覆盖已有的 README.md、rules.md、meta.md、project.md，使用 --force 时会覆盖这些受管 memory 文件。

🧠 .memory

.memory 用于保存长期有效的项目上下文，让 coding agent 能够快速恢复项目状态。

• README.md: Agent 入口文件，说明读取顺序、文件职责和维护边界。
• rules.md: memory 维护规则，说明何时创建、更新、删除和替换内容。
• meta.md: 项目必要元信息，包括项目名称、用途、阶段、技术栈、常用命令、环境说明和约束。
• project.md: 项目重要信息，包括当前目标、关键设计、关键修改、当前状态、TODO、已知问题和决策。

.memory 只维护以上四个文件。旧信息过期时直接更新或删除，不归档；Agent 应优先更新已有内容，避免重复追加。

Agent 使用流程

1. 初始化 memory：运行 vibefree init，生成 .memory 和 .harness。
2. 新 session 读取 memory：先读 .memory/README.md，再按顺序读 .memory/rules.md、.memory/meta.md、.memory/project.md。
3. 完成任务后更新 project.md：记录长期有价值的关键修改、当前状态、TODO、已知问题或决策。
4. 项目信息变化后更新 meta.md：维护项目用途、阶段、技术栈、常用命令、环境说明和约束。

不要创建旧结构文件或目录；不再使用 archive、logs、context.md、decisions.md、sessions.md。

🧭 .harness

.harness 用于保存 coding agent 的协作入口、架构说明、工作流和质量规则。

• AGENTS.md: agent 开始工作时的推荐读取顺序
• ARCHITECTURE.md: 系统结构和架构决策记录
• WORKFLOW.md: 开发流程和 memory 使用方式
• QUALITY.md: 测试、质量和安全规则
• plans/: 可选的任务计划目录

🗂️ 生成结构

.memory/
├── README.md
├── rules.md
├── meta.md
└── project.md

.harness/
├── AGENTS.md
├── ARCHITECTURE.md
├── WORKFLOW.md
├── QUALITY.md
└── plans/
    ├── active/
    │   └── .gitkeep
    └── completed/
        └── .gitkeep

🛠️ 本地开发

创建虚拟环境：

python -m venv venv

安装本地开发版本：

pip install -e ".[dev]"

运行测试：

pytest

构建发布包：

python -m build

✅ CI

项目使用 GitHub Actions 运行 CI。

• Pull Request 会自动运行测试和构建检查。
• push 到 main 或 master 会自动运行测试和构建检查。
• CI 会执行：
  • pip install -e .
  • pytest
  • python -m build
  • twine check dist/*

🚢 Release

项目通过 GitHub Actions 和 PyPI Trusted Publishing 发布到正式 PyPI。

当前 memory scaffolding 统一为四文件结构：README.md、rules.md、meta.md、project.md，并保持项目轻量。

发布流程：

1. 确认 pyproject.toml 中的 version 已更新。
2. 确认测试通过。
3. 创建并推送 tag：

git tag v0.2.0
git push origin v0.2.0

推送匹配 v* 的 tag 后，GitHub Actions 会构建包并发布到正式 PyPI。

发布使用 PyPI Trusted Publishing / OIDC，不推荐在仓库或 GitHub Secrets 中保存 PyPI API Token。

🔒 安全提示

• 不要把 token、API key、password、secret 或私有凭据写入 .memory 或 .harness。
• 提交前检查上下文文件，避免包含本地绝对路径、私有账号或临时调试信息。
• vibefree init 默认不会覆盖已有文件，但仍建议在重要项目中配合 Git 使用。

📄 License

Apache License 2.0. See LICENSE.