From 6c681feb355b2ceaf4176c4c44b51529c0f8d0e2 Mon Sep 17 00:00:00 2001 From: Adewale Abati Date: Thu, 21 Nov 2024 00:30:46 +0100 Subject: [PATCH] docs: Adding a .goosehints guide (#279) Co-authored-by: Angie Jones --- docs/configuration.md | 7 ++-- docs/guidance/getting-started.md | 3 ++ docs/guidance/using-goosehints.md | 54 +++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 4 files changed, 63 insertions(+), 2 deletions(-) create mode 100644 docs/guidance/using-goosehints.md diff --git a/docs/configuration.md b/docs/configuration.md index ef1d6002..93851897 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -17,7 +17,7 @@ default: requires: {} ``` -### Fields +### Fields #### provider @@ -104,6 +104,7 @@ unit-test-gen: ``` [jinja-guide]: https://jinja.palletsprojects.com/en/3.1.x/ +[using-goosehints]: https://block.github.com/goose/guidance/using-goosehints.html ## Adding a toolkit @@ -145,5 +146,7 @@ Goose ships with the ability to read in the contents of a file named `.goosehint This file will be read into the Goose system prompt if it is present in the current working directory. -> [!NOTE] +Check out the [guide on using .goosehints][using-goosehints] for more tips. + +> [!NOTE] > `.goosehints` follows [jinja templating rules][jinja-guide] in case you want to leverage templating to insert file contents or variables. \ No newline at end of file diff --git a/docs/guidance/getting-started.md b/docs/guidance/getting-started.md index cac0cf81..60f909ac 100644 --- a/docs/guidance/getting-started.md +++ b/docs/guidance/getting-started.md @@ -59,6 +59,8 @@ The following justfile shows our common commands: Write all code comments in French ``` +Check out the [guide on using .goosehints][using-goosehints] for more tips. + ### Toolkits Toolkits expand Goose’s capabilities and tailor its functionality to specific development tasks. Toolkits provide Goose with additional contextual information and interactive abilities, allowing for a more comprehensive and efficient workflow. @@ -139,3 +141,4 @@ goose session start --plan plan.md --args dep=pytest,repo=github [available-toolkits]: ../plugins/available-toolkits.md [providers]: ../plugins/providers.md [goose-plugins]:https://github.com/block-open-source/goose-plugins +[using-goosehints]: https://block.github.com/goose/guidance/using-goosehints.html diff --git a/docs/guidance/using-goosehints.md b/docs/guidance/using-goosehints.md new file mode 100644 index 00000000..352f7532 --- /dev/null +++ b/docs/guidance/using-goosehints.md @@ -0,0 +1,54 @@ +# Using `.goosehints` in Goose + +`.goosehints` are text files used within the Goose environment to provide additional context about your project and improve the communication between the developer and Goose. The use of `goosehints` ensures that Goose understands your requirements better and can execute tasks more effectively. + +>[!TIP] +> **Developer toolkit required** +> +> To make use of the hints file, you need to have the `developer` toolkit [enabled](https://block.github.io/goose/plugins/using-toolkits.html). + +This guide will walk you through creating and using your `.goosehints` file to streamline your workflow with custom instructions and context. + +## Creating your `.goosehints` file +You can place a `.goosehints` file in your current working directory or globally at `~/.config/goose/.goosehints`. This file can include any repeated instructions or contextual details relevant to your projects. + +A good time to consider adding a `.goosehints` file is when you find yourself repeating prompts, or providing the same kind of instructions multiple times. + +### Setting up hints + +The `.goosehints` file supports natural language and also follows [jinja templating rules][jinja-guide], so you can leverage templating to insert file contents or variables. + +Here are some ways people have used hints to provide additional context for Goose to follow: + +- **Decision-Making**: Specify if Goose should autonomously make changes or confirm actions with you first. + +- **Validation Routines**: Provide test cases or validation methods that Goose should perform to ensure changes meet project specifications. + +- **Feedback Loop**: Include steps that allow Goose to receive feedback and iteratively improve its suggestions. + +- **Point to more detailed documentation**: Indicate important files like `README.md`, `CONTRIBUTING.md`, or others that Goose should consult for detailed explanations. + +Like prompts, this is not an extensive list to shape your `.goosehints` file. You can include as much context as you need. + +Example `.goosehints file`: + +```jinja +This is a simple example JavaScript web application that uses the Express.js framework. View [Express documentation](https://expressjs.com/) for extended guidance. + +Go through the README.md for information on how to build and test it as needed. + +Make sure to confirm all changes with me before applying. + +Use the following custom values when needed: +{% include custom-config.js %} + +Run tests with `npm run test` ideally after each change. +``` + +## Best Practices + +- **Keep It Updated**: Regularly update the `.goosehints` file to reflect any changes in project protocols or priorities. +- **Be Concise**: Make sure the content is straightforward and to the point, ensuring Goose can quickly parse and act on the information. + + +[jinja-guide]: https://jinja.palletsprojects.com/en/3.1.x/ \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 14189029..ab4e0c9f 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -120,6 +120,7 @@ nav: - "Getting Started": guidance/getting-started.md - "Managing Goose Sessions": guidance/managing-goose-sessions.md - "Quick Tips": guidance/tips.md + - "Using Goosehints": guidance/using-goosehints.md - "Applications of Goose": guidance/applications.md - "Goose in Action": guidance/goose-in-action.md - Plugins: