vibefree 0.2.0

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
• 默认不覆盖已有文件
• 适合 opencode / coding agent 工作流
• 轻量、可读、可手动维护
• 支持当前目录初始化
• 支持创建新项目目录并初始化

📦 安装

从 PyPI 安装：

pip install vibefree

⚡ 使用

在当前目录初始化：

vibefree init

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

vibefree init my-project

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

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

🧠 .memory

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

• README.md: memory 入口说明、读取顺序和文件职责
• rules.md: memory 读取、更新和写作规则
• context.md: 当前项目目标、状态、常用命令、关注点和约束
• decisions.md: 长期技术决策、项目约定和需要避免的事项
• sessions.md: 最近会话交接记录
• archive/: 已归档但仍需保留的旧上下文

🧭 .harness

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

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

🗂️ 生成结构

.memory/
├── README.md
├── rules.md
├── context.md
├── decisions.md
├── sessions.md
└── archive/
    └── .gitkeep

.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。

0.2.0 是一次 memory scaffolding redesign，重点更新生成的 .memory 结构，并保持项目轻量。

发布流程：

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.